GitHub fine-grained PAT guidance for repod
repod only supports fine-grained personal access tokens (FGPATs). Do not use Tokens (classic) -- those use legacy scopes like repo / admin:org and do not match repod's permission checks or least-privilege recommendations.
Create the token (GitHub UI checklist)
- Go to Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens.
- Set Resource owner to the organization you want repod to sync (not your personal account).
- Set an Expiration (shorter is better; rotate regularly).
- Set Repository access:
- All repositories (recommended for accurate org-wide mapping), or
- Only select repositories (repod will show coverage gaps for repos not included).
If your org requires approval for fine-grained PATs, an org owner may need to approve the token request before it works.
Select permissions
Apply repo-to-team permission changes (repod write mode)
Use this only if you want repod to apply changes like:
- Add/remove a repository to/from a team
- Update a team's permission on a repository
Required permissions
| Area | Permission | Level |
|---|---|---|
| Organization | Members | Read |
| Organization | Organization private repositories | Read |
| Repository | Metadata | Read |
| Repository | Administration | Read and write |
GitHub's Add or update team repository permissions (and removal) requires Administration (write) + Members (read) + Metadata (read).
Optional add-on: Team management (CRUD) in the organization
Enable this only if you want repod (or your automation) to manage teams themselves, e.g.:
- Create / rename / delete teams
- Add/remove users to teams
- Optionally manage team membership via API
Add this permission on top
Organization permissions
- Members: Write (this is the key toggle)
Why
- Creating and deleting teams requires Members org permission (write).
- Adding/updating/removing team members requires Members org permission (write).
Notes: This is a meaningful increase in power. Use a dedicated machine user and rotate aggressively.
Troubleshooting (permission-to-symptom mapping)
- Teams not appearing / team hierarchy empty: Ensure Organization -> Members: Read.
- Private repos missing / repo list incomplete: Ensure Resource owner = your org and Repository access includes the repos (All or Selected).
- Apply changes fails (403) when updating team access to repos: Ensure Repository -> Administration: Write, plus Repository -> Metadata: Read and Org -> Members: Read.
- Team create/delete/member changes fail: Ensure Organization -> Members: Write.
Tip: GitHub REST responses may include X-Accepted-GitHub-Permissions, which tells you exactly what permission(s) the endpoint expects.
Mapping from classic PAT scopes (for clarity only)
- Classic admin:org (teams/members read) -> Fine-grained Organization: Members (read)
- Classic repo (repo visibility) -> Fine-grained Repository: Metadata (read) (plus include repos via Repository access)
- Classic write access actions -> Fine-grained Repository: Administration (write) (for team to repo permission updates)