co-maintainer

GitHub App

Automatic pull request reviews, webhooks, and the dashboard repositories all run through one GitHub App. The dashboard can create it for you, so the private key, webhook secret, and OAuth credentials are written straight into config.json instead of being copied between two screens.

serve runs the App. The App is not the same as CLI gh auth, which is only for reading a repository locally. See Authentication for the full picture.

Create it from the dashboard

  1. Start serve and open the dashboard.
  2. Set a public webhook address under Settings, Server.
  3. In the GitHub App card, keep or edit the suggested name and press Create GitHub App.
  4. GitHub shows the permissions and events listed below and asks you to confirm.
  5. GitHub redirects back, and serve writes the App ID, private key, webhook secret, and OAuth client ID and secret into config.json.

The suggested name is co-maintainer-<host>, shortened to fit GitHub's 34 character cap. App names are globally unique, so GitHub rejects a duplicate and the field stays editable. The button is refused, with the reason, until the webhook address looks reachable from GitHub. See Dashboard: Webhook reachability.

The creation is secured with a single-use server-side state that expires after ten minutes, so the callback cannot be replayed.

Install it on repositories

Creating the App does not install it. In GitHub, install the App on the organization or account that owns your repositories, and choose which repositories it can reach. The dashboard's Add repository list shows only repositories the App can already see.

Permissions

The manifest requests exactly the permissions the code uses, not a superset.

Permission Access Why
Contents Read Read files and PR_REVIEW_GUIDE.md, read the file tree, read commit history, compare two commits, read releases in the probe
Issues Read and write Read the conversation on a pull request, post a conversation comment, open an issue for a P0 or P1 commit watch finding, see whether a commit watch issue was closed, close a commit watch issue once its finding is fixed, create the co-maintainer and cm-P0 / cm-P1 labels, acknowledge a review request on the pull request, edit the failure note left on a pull request, acknowledge a review request in a comment
Pull requests Read and write List pull requests, read a pull request, read the files a pull request changes, read earlier reviews, read review comment threads, post a review, reply in a review comment thread
Checks Read and write Create the review check run, update the review check run
Metadata Read Read the repository and its default branch, check a commenter has write access before acting on a comment

Metadata is required by every GitHub App. The review check run is created through the App, never with a personal access token.

No administration, no actions, and no packages access is requested.

Events

Event Why it is subscribed
pull_request Open, synchronize, and close decide whether a review runs
pull_request_review Tracks review state for the auto-review rules
pull_request_review_comment Delivers a reply in an existing review comment thread
issue_comment Delivers a reply in a pull request conversation, and a comment on a commit watch issue

push is not subscribed by default. Tick it under Subscribe to events in the App's settings to turn on commit watch through the App. That applies to every repository the App is installed on, and the App reviews pushes to each repository's default branch only.

installation and installation_repositories are handled too, but they are not in the subscription list: GitHub delivers both to every App without a subscription, which is why the webhook handler accepts them.

Manual setup

If you would rather create the App by hand, use the same values:

co-maintainer set --github-app-id=... --github-app-private-key-path=./app.pem
co-maintainer set --github-webhook-secret=...
co-maintainer set --github-oauth-client-id=... --github-oauth-client-secret=...
co-maintainer set --github-oauth-allowed-user=your-github-login

Set the webhook URL to https://<your-host>/github/webhook and subscribe to the four events above. Configuration lists every flag and the three ways to supply the private key. OAuth is optional and only gates the dashboard sign-in. See serve: Sign in.

Rotating and moving the key

--github-app-private-key-file copies the key into config.json, so it keeps working if the file moves. --github-app-private-key-path stores only the path, so the secret never enters config.json and serve reads it at startup. If that file is missing, serve warns and continues. See Configuration: App private key.

If a new key is generated in GitHub, save it and run the set command again, or paste it into Settings. Credentials are read on every request, so the change applies without a restart.

Troubleshooting

Symptom Fix
Create GitHub App is refused Set a public webhook address first
App created but no review arrives Install the App on the repository, turn on auto-review in repo Settings, and confirm the webhook delivered
Settings save returns 422 The key or token is missing a scope GitHub requires
Webhook works but no review is posted Check the Activity job log, then the AI key and models under Settings

Webhook reachability problems are shown on each repository's Overview tab. See Dashboard: Webhook reachability.