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.Chart values
Provide the App’s details to the Chainloop backend underbackend.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
RotatingclientSecret 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.