GitHub PAT Scope Guidance

This page explains the minimum and recommended Personal Access Token (PAT) scopes for using the platform. Tokens are encrypted at rest; only limited operational metadata is stored. Rotate tokens at any time from the Organisation Management page.

Core Required Scopes

Scope	Why	Surface Impact
`repo`	Enumerate repositories (private + public) and read permissions for access planning previews.	Repo list, orphan detection, mapping export.
`admin:org`	Read teams / memberships structure; required for producing accurate Access Planner mapping templates.	Team hierarchy, team lookup during mapping import.

If you only sync public repositories you may drop private repo access, but unified permission logic will show reduced completeness.

Optional / Situational Scopes

Scope	When Needed	Notes
`read:org`	If using fine-grained PATs and only read access is permitted.	May substitute for `admin:org` in some limited visibility cases (reduced write capabilities).
`workflow`	If future features need CI workflow inspection for security posture.	Currently not required; defer granting until feature enabled.

Least Privilege Tips

Prefer a dedicated machine user or fine‑grained PAT bound to the specific org(s) you sync.
Rotate tokens periodically (e.g. every 90 days) or immediately after a member with knowledge of the token leaves.
Limit repository selection for fine‑grained PATs if you only manage a subset; missing repos will display as coverage gaps.
Remove unused PATs from the Org page to reduce attack surface.

Troubleshooting

Teams not appearing: Ensure admin:org (classic) or team read permissions (fine‑grained) are granted.
All repos show as public: PAT lacks private repo visibility—grant full repo scope.
Sync truncated: Check plan limits; view truncation note in the usage panel.
Permission mismatch errors: Re-export Access Planner mapping template to refresh validation lists after adding new teams.

Need another scope documented? Raise a ticket or open an issue referencing this page.