# Connect GitHub

Canonical URL: https://docs.fuse.init.inc/integrations/github/setup

Register the Init GitHub App and install it on a customer organization or account.



## Before you start [#before-you-start]

GitHub setup has two distinct stages:

1. **Engine operator** registers the platform GitHub App once (registration).
2. **Connection admin/user** installs that app on their organization or personal account (installation).

You need:

* Permission to create a GitHub App under the operator GitHub org or user that owns the platform app.
* Organization owner (or permitted admin) rights on the customer GitHub account that will install the app.
* The engine public base URL for callback and webhook URLs.

## Configure the provider [#configure-the-provider]

### Register the platform GitHub App (**Engine operator**) [#register-the-platform-github-app-engine-operator]

1. In GitHub, open **Developer settings → GitHub Apps → New GitHub App**.

2. Set the Callback URL to:

   `{FUSE_PUBLIC_URL}/v1/oauth/github/callback`

3. Configure webhook delivery to:

   `{FUSE_PUBLIC_URL}/v1/webhooks/github`

   and set a webhook secret.

4. Under **Permissions**, grant only the repository and organization permissions required by the Init actions you expose. Prefer read-only where possible.

5. Choose whether the app can be installed on any account or only on the owning account.

6. After creation, generate a private key and note the App ID, App slug, Client ID, and Client Secret.

7. Set the GitHub platform secrets in Doppler (`integrations-api` / matching env), using `.env.example` as the name catalog:

   * `GITHUB_APP_ID`
   * `GITHUB_APP_SLUG`
   * `GITHUB_APP_PRIVATE_KEY` (PEM private key)
   * `GITHUB_CLIENT_ID`
   * `GITHUB_CLIENT_SECRET`
   * `GITHUB_WEBHOOK_SECRET`

   Never commit these values.

Registration creates the app identity. It does not grant access to customer repositories until someone installs the app.

### Install on a customer account (**Connection admin/user**) [#install-on-a-customer-account-connection-adminuser]

Installation selects the org/user and repositories the app may access. That step happens through Init Connect, not by pasting tokens.

## Connect to Init [#connect-to-init]

1. **Connection admin/user** starts a GitHub Connect session.
2. GitHub opens the install flow for the platform app slug (`https://github.com/apps/{GITHUB_APP_SLUG}/installations/new`).
3. Choose the organization or user, then **All repositories** or **Only select repositories**.
4. Complete any user authorization step Init requires for the installation callback.
5. Init verifies the installation ID against the expected App ID and stores the connection.

No customer credential form fields are submitted for GitHub.

## Permissions [#permissions]

Installation permissions are those configured on the GitHub App. The generated scope matrix maps Init actions to GitHub App permission strings (for example repository contents or issues).

Organization owners can restrict who may install apps. Repository admins may be limited to installing with access only to repositories they administer.

If Init enables optional issue-write actions in your deployment, the app registration must include the matching issues write permission before customers reconnect.

## Verify the connection [#verify-the-connection]

1. Confirm Connect completes and Init shows an active GitHub connection bound to the expected installation.
2. Run a safe read-only call such as listing repositories visible to the installation.
3. Success looks like a verified installation ID for the platform App ID and a read response without `401`/`403` from GitHub.

## Rotate or revoke access [#rotate-or-revoke-access]

* **Rotate app credentials (Engine operator):** generate a new private key or client secret in GitHub App settings, update `GITHUB_APP_PRIVATE_KEY` / `GITHUB_CLIENT_SECRET` / `GITHUB_WEBHOOK_SECRET`, then revoke old material.
* **Change repository access (Connection admin/user):** update the installation’s repository selection in GitHub, or reconnect through Init.
* **Revoke:** uninstall the GitHub App from the organization or user, then delete or reconnect the Init connection.
* After increasing app permissions, customers must accept the permission update on the installation (reconnect/reauthorize as prompted).

## Troubleshooting [#troubleshooting]

| Symptom                      | What to check                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| Callback mismatch            | Callback URL must be `{FUSE_PUBLIC_URL}/v1/oauth/github/callback`.                       |
| Installation not verified    | App ID in GitHub must match `GITHUB_APP_ID`; wrong app slug installs a different app.    |
| Missing repository access    | Installation may be limited to selected repos; adjust selection or reinstall.            |
| Permission denied on actions | App permissions must cover the action; accept permission updates after operator changes. |
| Org blocks installs          | Ask an organization owner to approve or install the app.                                 |