Self-host the hub: GitHub App

Self-host the hub

GitHub App

Generate the GitHub App manifest from your hub URL, create the app, and give the hub its credentials.

The hub talks to GitHub through a GitHub App that you own. The repository ships a generator that writes the manifest for your hub URL.

Generate the manifests

From the repository root, run the generator with your hub URL.

node scripts/gen-manifests.mjs --hub-url https://hub.example.com

See the header of scripts/gen-manifests.mjs for the supported options and the output location. The generated files are written to hub/manifests/, one for GitHub and one for Slack. They contain URLs only, no secrets.

Create the app

  1. Open the generated GitHub manifest in hub/manifests/. Check that the hub URL in it is your hub URL.

  2. Create the app on GitHub, either from your account (Settings, Developer settings, GitHub Apps) or from an organization’s settings. If you use GitHub’s manifest flow, submit the manifest content as GitHub describes in its documentation for creating an app from a manifest.

  3. Confirm the permissions listed below on the app’s Permissions page.

  4. Generate a private key on the app page and download the .pem file.

  5. Note the App ID, the client ID, and a client secret you generate.

  6. Install the app on the account or organization whose repositories you want to run checks for.

Permissions

Permission Access
Contents Read
Metadata Read
Pull requests Read
Members Read
Checks Write

The hub reports results as Check Runs with annotations. It does not write commit statuses.

Webhook

The app’s webhook URL and events are set in the manifest. Use the webhook URL printed by the manifest script, and check it matches your hub URL. Set a webhook secret and keep the same value for GITHUB_WEBHOOK_SECRET below. After installing, GitHub’s app page lists recent deliveries under Advanced. A successful delivery shows a 2xx response.

Set the secrets

Run these from hub/. Wrangler prompts for each value.

npx wrangler secret put GITHUB_APP_ID
npx wrangler secret put GITHUB_APP_PRIVATE_KEY
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put GITHUB_WEBHOOK_SECRET

For GITHUB_APP_PRIVATE_KEY, paste the full PEM including the BEGIN and END lines. If the Worker rejects the key format, check how the hub reads this variable in hub/src.

Secrets take effect on the next request. Run npx wrangler deploy again if Wrangler asks for it.

Verify

  1. Open the app’s Advanced tab on GitHub and use Redeliver on a recent delivery.
  2. The response should be 2xx.
  3. Run npx wrangler tail in hub/ while redelivering to watch the request arrive.

Continue with Slack App.