GitHub App¶
Arnold reviews GitHub pull requests through a GitHub App that you create and own. The app gives Arnold:
- user-to-server tokens, so actions in Arnold (comments, reviews, approvals, resolving threads) are performed as the signed-in user;
- installation tokens, short-lived and scoped to one repository, which runners use to clone and post review comments as the app;
- webhooks (optional) for instant pull request updates.
github.com and GitHub Enterprise Server are both supported.
Two different GitHub registrations
The GitHub App on this page is for reviewing code. Signing in to Arnold with GitHub uses a separate GitHub OAuth App (see Sign-in), and so does the optional Copilot harness (see LLM).
1. Create the app¶
Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App (or the same page under an organization's settings to own it there).
| Field | Value |
|---|---|
| GitHub App name | Anything unique, e.g. acme-arnold. Its URL name is the slug |
| Homepage URL | Your Arnold URL, e.g. http://localhost:3000 |
| Callback URL | <ARNOLD_UI_URL>/github/oauth/callback, e.g. http://localhost:3000/github/oauth/callback. Must match exactly |
| Expire user authorization tokens | Checked |
| Request user authorization (OAuth) during installation | Optional |
| Enable Device Flow | Unchecked |
| Setup URL | Blank |
| Webhook → Active | Unchecked for local use. For a reachable deployment, see webhooks |
| Where can this GitHub App be installed? | Only on this account for a single org; Any account to let others install it |
Repository permissions
| Permission | Access | Used for |
|---|---|---|
| Pull requests | Read & write | Read PRs, post comments and reviews, resolve threads |
| Contents | Read | Clone the code, read files and diffs |
| Checks | Read | Merge checks in the review workspace |
| Commit statuses | Read | Merge checks in the review workspace |
| Metadata | Read | Mandatory |
No organization or account permissions are needed.
2. Collect credentials¶
On the app's settings page:
- Note the App ID: a number such as
1234567, not the name. - Note the Client ID:
Iv1.…orIv23…. - Generate a new client secret and copy it.
- Generate a private key. A
.pemfile downloads. - Install App on the accounts and repositories Arnold should review. You need admin rights on them; to try Arnold on a public project you do not own, fork it and install the app on the fork.
3. Configure Arnold¶
GITHUB_APP_ENABLED=true
GITHUB_APP_ID=1234567
GITHUB_APP_SLUG=acme-arnold
GITHUB_APP_CLIENT_ID=Iv23...
GITHUB_APP_CLIENT_SECRET=...
GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----
The private key must be on one line with literal \n between lines. Convert the downloaded file with:
PKCS#1 (BEGIN RSA PRIVATE KEY) and PKCS#8 (BEGIN PRIVATE KEY) keys both work.
For GitHub Enterprise Server, also set:
Apply and connect:
In Arnold, open Settings → Connected accounts → GitHub → Connect, authorize the app, and you are sent back to Arnold. The setup guide then offers Install Arnold on repositories if the app is not installed anywhere yet.
4. Webhooks (optional)¶
Without webhooks, repository sync re-imports open pull requests every few minutes. With them, updates are immediate.
- In the app settings, check Webhook → Active.
- Webhook URL:
https://<backend-host>/github-callbacks/v1/events. Expose the backend for this path; the UI's/apiproxy only forwards it in development mode, because it requires a signed-in session otherwise. - Set a random Webhook secret and put the same value in
GITHUB_APP_WEBHOOK_SECRET. - Under Permissions & events → Subscribe to events, select Pull request and Pull request review.
Arnold verifies X-Hub-Signature-256 and ignores duplicate deliveries (X-GitHub-Delivery).
For local testing, relay webhooks with smee.io:
How runners authenticate to GitHub¶
When the app is configured, the backend mints an installation token for the pull request's repository and adds it to
each job as SCM_GITHUB_TOKEN. Runners then need no GitHub credential of their own, and comments are authored by the
app (acme-arnold[bot]).
Limitations¶
- Apply suggestion is not supported on GitHub. Use GitHub's own Commit suggestion.
- A user sees a pull request in their queue only after connecting their GitHub account. All synced pull requests are always visible under Merge Requests → All open.
Troubleshooting¶
| Symptom | Fix |
|---|---|
Incorrect type of value at: …githubConfiguration.appId |
GITHUB_APP_ID must be the numeric ID |
| GitHub shows a redirect_uri error when connecting | The app callback URL must equal <ARNOLD_UI_URL>/github/oauth/callback exactly |
GitHub integration is not configured |
GITHUB_APP_ENABLED, client id or secret missing; recreate server |
| Runner: SCM token required for MR link parsing | The app is not installed on that repository, or the App ID/private key is wrong. Check the server log for installation token warnings |
| HTTP 401 Bad credentials minting tokens | Wrong key, or the host clock is skewed (common with Podman after sleep); see Troubleshooting |