Skip to main content
To enable GitHub repository onboarding on a self-hosted Chainloop instance, create a GitHub App and provide its credentials to the Chainloop backend through Helm chart values. This is a one-time, operator-level setup step — once configured, your users connect their GitHub organization from the Chainloop UI following the Connect GitHub & GitLab flow.

Create the GitHub App

1

Create the App on GitHub

Follow GitHub’s guide to creating GitHub Apps to register a new App under your GitHub organization (or personal account, for testing).
2

Grant the required permissions and events

Configure the App’s repository and organization permissions and subscribe to the two webhook events Chainloop needs: pull_request and pull_request_review. See the cumulative permission set for the full, up-to-date list of scopes, and subscribed webhook events for what each event drives.
On an App you created earlier, check that pull_request_review is subscribed. Without it, a pull request is not re-validated when a reviewer approves, requests changes, or has their review dismissed. The event needs no permission beyond Pull requests: Read, which the App already has.
3

Collect the App ID

On the App’s settings page, note the App ID shown near the top. You’ll set this as appId.
4

Generate a client secret and collect the client ID

Under General → Client secrets, click Generate a new client secret. GitHub displays it once and never returns it from the API — record it before leaving the page. You’ll set it as clientSecret, and the Client ID shown just above it as clientId.
5

Register the OAuth callback URL

Under Identifying and authorizing users, add a Callback URL of <backend-external-url>/enroll/github/authorize/callback. Add it alongside any existing entries without reordering them.Leave Allow wildcard matching off. Chainloop sends redirect_uri explicitly on every authorization request, so ordering and wildcards are unnecessary — and a wildcard would let OAuth codes reach subdomains and sub-paths.Leave Request user authorization (OAuth) during installation unchecked. See the warning below.
6

Set the Setup URL

Under Post installation, set the Setup URL to <backend-external-url>/enroll/github/callback and keep Redirect on update checked. This is what returns a user to Chainloop after they install the App, or after they add or remove repositories on an existing installation.
7

Generate a private key

Under Private keys, click Generate a private key. GitHub downloads a PEM file — you’ll set its contents as privateKey.
8

Note the app slug

The App’s public URL is of the form https://github.com/apps/<app-slug>. Copy the <app-slug> segment — you’ll set this as appSlug.
9

Set a webhook secret

Under Webhook, set a Secret — a random string used to verify that incoming webhook requests genuinely came from GitHub. You’ll set this as webhookSecret. Set the Webhook URL to <backend-external-url>/github/events.
Do not enable Request user authorization (OAuth) during installation. Selecting it removes the Setup URL field from the App’s settings entirely, which breaks both the connection flow and the add/remove-repositories flow — with no error shown in the Chainloop UI or in the backend logs. Because it changes the App registration rather than the deployment, rolling back a Chainloop image does not undo it.

Chart values

Provide the App’s details to the Chainloop backend under backend.githubApp in your Helm chart values:
clientId and clientSecret are required whenever backend.githubApp is set, together with a resolvable backend external URL. The backend refuses to start without them. Deployments with no GitHub App configured are unaffected.
These values apply to both the OSS chart (chart: platform) and the Enterprise chart (chainloop-ee) — the value paths are identical.

Why the OAuth credentials are required

When a user connects their GitHub organization, Chainloop binds a GitHub App installation to their Chainloop organization. Before creating that binding it confirms the person completing the flow has access to the installation they’re binding, by sending them through the App’s user-to-server OAuth flow. The App’s private key cannot answer that question — it identifies the App, never the human in the browser — and minting a user access token requires the OAuth client credentials. Users see one extra GitHub authorization prompt the first time an installation is bound. Re-running the flow against an installation the organization already holds skips it, so adding and removing repositories is unaffected. See installer verification for what Chainloop checks and which token it uses.

Backend external URL

The OAuth callback URL is derived from the backend’s externally reachable origin by appending /enroll/github/authorize/callback. GitHub matches redirect_uri byte for byte against the registered Callback URL, so the two must agree exactly — including scheme, and with no trailing slash on the origin. You don’t set this origin under githubApp. The chart derives it from the first of these that is set: The resolved callback URL is logged by the backend at startup, so you can copy it verbatim into the App’s Callback URL list:

Rotating the client secret

Rotating clientSecret invalidates connection flows that are in progress at the moment of the rollout — the key protecting the OAuth state parameter is derived from the secret, so a flow that started before the change fails on its return leg. Affected users simply start the connection again. Installations already bound are unaffected, and no repository data is lost.

Troubleshooting

GitHub Enterprise Server: set baseUrl to your GHES URL — all features are supported the same way as on github.com. baseUrl also determines where the OAuth endpoints and the REST API are reached (<ghes-host>/login/oauth/* and <ghes-host>/api/v3), so no additional configuration is needed.