GitHub App permissions
The repository permissions the Spectrace GitHub App requires, why each one is needed, and the webhook events it handles.
reference/github-app-permissions.mdx — do not edit it by hand.Generated from REQUIRED_APP_PERMISSIONS in apps/web/src/lib/github/app-credentials.ts (events from apps/web/src/app/api/webhooks/github/app/route.ts) by apps/web/scripts/docs/generate.ts — do not edit by hand.
Use this page to check what the Spectrace GitHub App asks for on a repository, and to see why each permission is required.
Spectrace requires 4 repository permissions. The list is the same constant the app uses to compare a registration against what GitHub reports back from GET /app: a permission that is missing or granted at a lower level than listed is reported as a configuration problem. Granting Read & write satisfies a Read-only requirement; the reverse does not.
Repository permissions
| Permission | Access | Why |
|---|---|---|
pull_requests | Read & write | Read the pull request and its changed files, and submit a review (approve, request changes, or comment) on it. |
issues | Read & write | Post the PR summary comment. GitHub serves POST /issues/{n}/comments under Issues, not Pull requests, so without this the summary comment fails with 403. |
checks | Read & write | Publish the verification result as a check run on the head commit. |
contents | Read-only | Read file contents. The changed-file diff itself is served under Pull requests (GET /pulls/{n}/files), not Contents. |
GitHub adds metadata: read to every App that requests any repository permission. It is not in the constant because GitHub grants it on its own; it appears on the installation screen regardless.
Webhook events the App handles
The App has one webhook URL, /api/webhooks/github/app. Every delivery's signature is checked against GITHUB_APP_WEBHOOK_SECRET before the payload is parsed; an unset secret or a bad signature is rejected with 401. The route branches on these X-GitHub-Event values; any other event is acknowledged with 200 and skipped:
| Event | What Spectrace does with it |
|---|---|
ping | Confirms the webhook URL is reachable when the App is registered. |
installation | Records, removes, suspends, or unsuspends an installation, and updates its granted permissions when the account accepts new ones. |
installation_repositories | Updates which repositories an installation covers when the account adds or removes them. |
pull_request | Resolves the repository to a project through the installation. On opened, synchronize, and reopened it queues PR verification; on closed with the PR merged it marks the requirement the PR was matched to as done and syncs that status to the linked tracker. Other actions, and repositories nobody has mapped to a project, are acknowledged and skipped. |
installation and installation_repositories are sent to every GitHub App automatically; pull_request must be subscribed to on the App's registration page, and its checkbox only appears once the pull_requests permission is set.