Connect GitHub

Agent markdown

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

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)

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

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

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

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 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