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.
Related guide: GitHub repo naming, nested teams, and permissions for private orgs.
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)
Once PAT scopes are working, continue with our guide to GitHub repo naming, nested teams, and permissions to shape the wider org model.