Connect GitHub (GitHub App)

The recommended way to deploy from GitHub is Falak’s GitHub App connection. Falak registers a private GitHub App for your Falak organization through GitHub’s app manifest flow; you confirm it on github.com and pick the repositories Falak may deploy. No personal access tokens, no deploy keys, no per-repository webhooks.

Prerequisites

• An organization owner or admin in Falak (permission source_control.manage).
• A GitHub account, or a GitHub organization you own.
• For push-to-deploy: GitHub must be able to reach your panel over HTTPS.

Connect

1. Open Settings → Source control and click Connect GitHub.

2. Choose where the app lives: your personal GitHub account, or a GitHub organization you own (type its name).

3. On github.com, confirm the app. Falak stores its id, private key and webhook secret encrypted in its database.

4. GitHub continues to the installation page. Pick All repositories or Only select repositories, then install.

5. GitHub sends you back to Falak. The connection appears in the list and its repositories are available in the Git repository picker.

To change which repositories Falak can see later, click Manage access on GitHub on the connection. GitHub sends you back afterwards and Falak refreshes the list.

What the app can access

Permission / event	Access	Why
Repository contents	Read-only	Clone your code for builds
Metadata	Read-only	List repositories and branches
push event		Push-to-deploy

The app has no write access, no administration permission (so Falak adds no deploy keys), and no statuses, checks or pull_requests permissions (Falak does not report commit statuses and has no preview deployments yet).

Clone tokens: builds clone over HTTPS with an installation token minted per build. Tokens are valid for one hour, cached for at most 50 minutes, and never stored or logged.

The webhook

The app has a single webhook for all its repositories:

https://<panel>/api/webhooks/source-control/github-app/<app-id>

It is shown on the connection card. Deliveries are verified with the X-Hub-Signature-256 header and limited to 600 per minute per app (FALAK_GITHUB_APP_WEBHOOK_RATE_LIMIT).

• Creating the app and cloning work without the webhook.
• Push-to-deploy and installation status changes (suspended, uninstalled) need it.
• If GitHub must reach Falak under another hostname, set FALAK_WEBHOOK_URL (the public base URL) on the control plane.

Rules and limits

• One app per Falak organization. A private GitHub App can only be installed on the account that owns it. To deploy repositories from a second GitHub account, create another Falak organization, or use a token connection.
• An installation already connected to a different Falak organization is refused.
• While an installation is suspended on GitHub, Falak refuses to mint tokens for it.

Disconnect or delete

Action	Effect
Disconnect (on an installation)	Uninstalls the app from that GitHub account
Delete app	Uninstalls it everywhere and forgets its credentials

The app registration itself stays on GitHub. Delete it under the app’s settings on GitHub → Advanced.

Operator-managed app (optional)

To use one GitHub App you created yourself for every Falak organization, set these on the control plane and restart:

Variable	Value
GITHUB_APP_ID	The app’s numeric id
GITHUB_APP_SLUG	The app’s URL name (github.com/apps/<slug>)
GITHUB_APP_PRIVATE_KEY	The PEM private key (newlines may be written as \n)
GITHUB_APP_WEBHOOK_SECRET	The webhook secret

Configure that app on GitHub with:

• Setup URL https://<panel>/source-control/github-app/setup, with Redirect on update on;
• Webhook URL https://<panel>/api/webhooks/source-control/github-app/env;
• Permissions Contents: read and Metadata: read, and the push event.

When set, the operator app takes precedence for new installations (existing ones keep their app), and the one-click registration is hidden.

Where to put these variables

The Compose stack passes only a fixed list of variables from /opt/falak/.env into the app containers, and GITHUB_APP_* is not on it. Put them in /opt/falak/custom.env, which is loaded into every app container, then run falak-ctl up.

Verification status

The GitHub App flow is covered by automated tests with a faked GitHub and was verified by hand against real GitHub on a production install (Falak 0.2.x): creating the app from the manifest, installing it on repositories, cloning private repositories with installation tokens, and push-to-deploy through the app webhook.

Next steps

Push-to-deploy and deploy hooksDeploy on every push, or from CI.

Tokens, GitLab, Bitbucket, custom gitOther ways to connect.