The GitHub App

A self-hosted Instance acts on GitHub through a GitHub App you register yourself — the same bring-your-own posture as the identity issuer. (On app.specbench.io this is preconfigured; nothing on this page applies there.) It's one-time setup for the Instance; afterwards, organizations install the App and projects connect exactly as described in Connecting to source control.

1. Register a GitHub App

Create a GitHub App under your GitHub organization (or user account): Settings → Developer settings → GitHub Apps → New GitHub App.

• GitHub App name — anything; the App's URL slug is what Specbench needs.
• Homepage URL — your Instance's URL.
• Setup URL (under Post installation, not the user-authorization callback URL) — https://<your-instance>/api/v1/sourcecontrol/installations/callback, with "Redirect on update" enabled. Leave it blank and GitHub never sends the installer back, so the Instance never learns the App was installed.
• User authorization callback URL — leave blank. This Instance never acts as the signed-in GitHub user, so it needs no client secret.
• Webhook — disable it; this Instance does not consume webhooks yet.
• Repository permissions — Metadata: Read-only. That is all the current flow needs; publishing specs will ask for write access when it ships.
• Where can this App be installed? — "Any account" if several GitHub orgs will install it; "Only on this account" otherwise.

After creating it, note the App ID and generate a private key (a .pem file).

2. Configure the Instance

Set the App's identity in the API's environment (the release's annotated env.example lists all three):

GitHubApp__AppSlug=your-app-slug
GitHubApp__AppId=123456
# Either inline — a `.env` value must be ONE line, so escape the PEM's
# newlines as \n...
GitHubApp__PrivateKeyPem="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
# ...or a path the API container can read. The compose file mounts no
# volumes into the api service, so this option means adding one yourself:
GitHubApp__PrivateKeyPath=/secrets/github-app.pem

Leave all of these unset to run without source control — the UI will say the Instance Operator needs to configure the GitHub App. Partial configuration fails at startup, naming the missing setting, and so does a private key the API cannot read or parse.

Persist the data protection key ring

The install flow hands GitHub a signed state token that stays valid for 30 minutes, and verifies it when GitHub redirects back. It is signed with ASP.NET Core's data protection key ring. With the default in-container key location, a restart — or a second replica that has its own keys — invalidates tokens that are still in flight, and the callback fails with sourcecontrol.state.invalid.

If you run more than one API replica, or your containers have no persistent volume, point data protection at shared, durable storage so every replica signs and verifies with the same keys.