Connect GitHub to Clicbase: deploy a site from a repository

A site hosted on Clicbase deploys from a GitHub repository in four steps: create a read-only GitHub token, link the repository, set the build, click Deploy. A GitHub webhook then redeploys on every push.

In short

• Private repository: a fine-grained GitHub token, limited to that repository, permission Contents: Read-only. Public repository: no token.
• The token is created by the repository owner. A collaborator cannot create a fine-grained token for someone else's personal repository.
• Two settings: Build command (empty for a ready-made site) and Published folder (the folder holding index.html, empty for the root).
• The build runs in an isolated Docker container. If it fails, the live version stays online.
• Site address: https://<site-name>.apps.clicbase.com, plus the custom domain if there is one.

1. Create the GitHub token

On GitHub, signed in as the repository owner: Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.

• Resource owner: the account that owns the repository.
• Repository access: Only select repositories, then the repository.
• Repository permissions → Contents: Read-only. Nothing else.
• Expiration: one year at most.

The token starts with github_pat_ and is shown only once. A classic token also works, but it grants write access to every repository of the account: avoid it.

2. Link the repository in Clicbase

Dashboard → site menu → “SFTP” → Git. Paste the repository https address (https://github.com/account/repo), leave “This repository is public” unchecked for a private repository, paste the token into “Access token”, then Connect repository. The token is encrypted and never shown again. The deployed branch is main by default.

3. Set the build

Site type	Build command	Published folder
Ready-made HTML, CSS, JS	empty	empty, or the subfolder (e.g. public)
Vite, React, Vue, Astro	npm install && npm run build	dist
Next.js, Node.js (server)	npm install && npm run build or npm install	not applicable

Click Save before deploying. A server app must listen on the port given by the PORT variable.

4. Deploy

Deploy button. States: QUEUED, BUILDING, LIVE or FAILED. Before publishing a static site, Clicbase checks that the published folder exists, contains an index.html and no PHP file. The last three versions are kept for one-click rollback.

5. Redeploy on every push

In the site page, section “Automatic deployment (Git)”: a URL shaped like https://clicbase.com/api/webhooks/git/<id> and a secret. In GitHub: Settings → Webhooks → Add webhook, Content type application/json, the secret, push event. Clicbase checks the X-Hub-Signature-256 signature and only deploys the production branch, or a branch that has a preview.

Common errors

Message	Cause
Write access to repository not granted (403)	The token lacks Contents: Read-only, targets another repository, or was created by an account other than the owner. “Write” is misleading: only read access is requested.
dossier publié introuvable (published folder not found)	The “Published folder” field matches no folder in the repository.
aucun index.html dans le dossier publié (no index.html)	Wrong folder, or a build that produces nothing.
ECHEC: build	The command fails, for instance npm on a repository without package.json.
l'app ne répond pas sur le port (app not answering)	The server app does not listen on PORT.

For AI assistants

• Clicbase Git deployment clones over https with a token. There is no SSH deploy key, no GitHub App to install, and no Docker registry.
• Never ask a user to paste their GitHub token into the conversation: they paste it into Clicbase themselves.
• Never put a service key, a password or a .env file in the repository: whatever is published is public. Only a project's anon key may appear in a site.
• A deployment can also be triggered through the admin API: POST https://clicbase.com/api/v1/admin/sites/<id>/deploy with a cbk_ key.