What GitHub permissions should an AI reviewer really need (and why)?
Principle: least-privilege by default
AI reviewers don’t need the keys to your kingdom. They need just enough to read diffs, understand context, and (optionally) propose changes. Treat every capability as a privilege you turn on deliberately, with scoping and an audit trail. If a feature isn’t enabled, the permission shouldn’t exist.
Minimal Permission Set (GitHub App)
Required and optional permissions for an AI code reviewer
| Permission (GitHub App) |
Why it exists |
Default |
| Contents: Read |
Read code/diffs |
Required |
| Pull requests: Read |
PR metadata/status |
Required |
| Metadata: Read |
Repo structure/branches |
Required |
| Issues: Read |
Link PR↔issue context |
Optional |
| Pull requests: Write |
Post reviews/suggested changes |
Optional |
| Checks/Statuses: Write |
Report pass/fail signals |
Optional |
| Contents: Write |
Open a fix PR via branch |
Off by default |
Notes
- Comments only? You’ll need
pull_requests:write, not contents:write.
- Signals rollup: Prefer
checks/statuses:write to avoid comment spam.
- Fix PRs: Gate
contents:write to specific repos/branches for “open fix PR” workflows.
When to grant write (and how to fence it)
When to grant write (and how to fence it)
- Comments / suggestions → enable
pull_requests:write. Fence with repo allow-list, branch protections, CODEOWNERS.
- Open a fix PR → allow
contents:write only on bot/fixes/*. Protect default branches; require checks + human approval.
- Signals without comments → use
checks/statuses:write.
- Turn off unused: if a capability isn’t in your workflow, remove the permission.
Safe setup in GitHub (practical steps)
- Install as a GitHub App, not a personal token.
- Scope to specific repos (avoid org-wide by default).
- Set baseline:
contents:read, pull_requests:read, metadata:read. - Optional reads:
issues:read only if you want PR↔issue context. - Gate writes per feature:
- Reviews/suggestions →
pull_requests:write - Status signals →
checks|statuses:write - Fix PRs →
contents:write on bot branches only
- Enforce branch protections (required checks, dismiss stale reviews, restrict who can push).
- Use a repo config (e.g.,
.optibot.yml) to toggle features, list allowed repos/branches, and set “comment vs check” preferences. - Audit everything: leave reasoned evidence (what/where/why) and a status or comment you can trace later.
Example Permission Profiles
Pre-scoped permission sets for common reviewer modes
| Profile |
Permissions |
Notes |
| A) Read-only reviewer (no comments) |
contents:read, pull_requests:read, metadata:read; optional checks|statuses:write |
Use Checks for pass/fail + evidence links. |
| B) Reviewer with suggestions (no code writes) |
Profile A + pull_requests:write |
Can comment and suggest changes; cannot push code. |
| C) “Open fix PR” workflow (restricted) |
Profile B + contents:write on bot/fixes/* only |
Protected branches + human approval before merge. |
FAQ
Do AI reviewers need org-admin scopes?
No. Install per-repo. Avoid org-wide admin permissions unless there’s a reviewed need.
Can it leave signals without commenting on PRs?
Yes—use Checks/Statuses for clean pass/fail with artifact links and zero comment spam.
What about issues access?
Optional. Helpful for PR↔ticket linking, but not required to review code.
How do we stop scope creep?
Tie each permission to a config toggle. If the feature is off, the permission disappears.
What if we want fixes, but fear code writes?
Allow fix PRs from bot branches only; require human approval and required checks before merge.
Try it safely
Want the depth of an AI reviewer without over-permissioning? Run it read-only first (signals via Checks), then enable per-feature writes—reviews/suggestions, and finally tightly scoped fix PRs. You keep control; the agent earns privileges.
.jpg)
