Guide
Configure Token Scopes
Map GitHub token permissions to each preset and tool family.
Every tool call hits the GitHub REST API with the token you provide. Scoping that token correctly is the first line of defense.
Create a fine-grained token
Fine-grained personal access tokens let you restrict access per repository and per permission category. This is the recommended type for any production assistant.
- Go to github.com/settings/personal-access-tokens/new
- Select only the repositories your agent needs
- Enable permissions based on the preset you plan to use (see matrix below)
Map permissions to presets
| Preset | Repository access | Contents | Pull requests | Issues | Actions | Administration |
|---|---|---|---|---|---|---|
repo-explorer | selected repos | read | — | — | — | — |
code-review | selected repos | read | read (or write for comments) | — | — | — |
issue-triage | selected repos | read | — | write | — | — |
ci-ops | selected repos | read | — | — | write | — |
maintainer | selected repos | write | write | write | write | write (for repo creation and forking) |
Apply least-privilege step by step
Start with read-only
Enable only contents: read and use preset: 'repo-explorer'.
Validate in staging
Run the agent against a test repository and review all tool calls before adding write scopes.
Add writes for approved operations
Enable write permissions only for the specific families you need, and combine with approval control.
Safest baseline: fine-grained token + narrow preset +
requireApproval: true.