FlatRun deploys any Git repository from its URL. For GitHub that takes two optional extras: a token for a private repository, and a webhook so a push deploys the project and each pull request gets a preview.
1. Create the project
Open New project, choose Git repository and paste the
repository URL, for example https://github.com/acme/web.git. Set the branch to
deploy, and under Advanced a subdirectory when the app does not live at the
repository root. FlatRun runs the Compose file it finds there, otherwise builds the
Dockerfile, otherwise detects the language with Railpack.
2. Private repositories
Create a GitHub token that can read the repository:
- Fine-grained token (recommended): limited to the repository, with Contents: Read-only.
- Classic token: the
reposcope.
Paste it under Advanced → Access token. Leave Save this token for later deploys ticked: the token is saved under the repository's name, so every deploy on push can fetch the repository again. The next private repository can pick it under Repository access. Saved tokens stay on the server and are masked in API responses. Untick the option to use a token once, for a project you will not redeploy.
3. Deploy on every push
Open the project's Deployments section. The Webhook card shows
the address for GitHub, https://your-server/api/hooks/github/<project>. Choose
Create secret; the secret is shown once.
In the repository on GitHub, open Settings → Webhooks → Add webhook and set:
| Field | Value |
|---|---|
| Payload URL | The GitHub address from the Webhook card |
| Content type | application/json |
| Secret | The secret from the Webhook card |
| Events | Pushes and Pull requests |
Then turn on Deploy on push in the Source card. A push to the project's branch deploys that commit; pushes to other branches are ignored. FlatRun checks every delivery's signature against the secret and refuses one that does not match. The server must be reachable from GitHub at that address.
4. Pull request previews
Turn on Pull request previews in the Source card. Each opened pull request gets its own environment built from its branch, updated on every push to it, and removed when the pull request closes. Previews need the Pull requests event on the webhook.