# Connect GitHub (GitHub App)

> Connect GitHub to Falak in one click with a private GitHub App — read-only repo access, per-build clone tokens and one push webhook — or an operator app.

Source: https://falak.sh/docs/guides/connect-github/

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:

```text
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](/docs/guides/connect-git-tokens/).
- 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.

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