GitHub fine-grained PAT scopes for repod
repod accepts only fine-grained personal access tokens (FGPATs) for new org connections and token rotation. 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 org permissions governance guide.
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.
Permission boundary summary
- No private source-code access in the required permission set: repod does not require Repository -> Contents permission. GitHub requires Repository Contents read for private repository contents, README, archive, and source-content APIs. Do not add Contents permission for repod.
- No organization invitations in core workflows: core sync, reporting, repo-to-team apply, and repository metadata workflows require Organization -> Members read at most. GitHub requires Organization -> Members write to create or cancel organization invitations.
- Elevated exceptions: optional Team management requires Organization -> Members write and must be treated as a separate elevated mode. If your policy requires organization invitations to be technically impossible from the repod token, do not enable Team management or grant Members write.
- Repository collaborator boundary: Repository -> Administration write can add or remove repository collaborators. That is not the same as inviting a user into the GitHub organization, but it can invite or grant direct repository collaborator access where GitHub permits it.
Select permissions
Core sync and reporting (repod read mode)
Use these permissions for connecting an org, syncing repositories/teams, showing org maps, and producing governance reports.
| Area | Permission | Level | Why repod needs it |
|---|---|---|---|
| Organization | Administration | Read | Read org-level settings such as base repository permission. |
| Organization | Members | Read | Read teams, team membership, and team-repo access. |
| Repository | Metadata | Read | List repositories and retain stable GitHub repository IDs. |
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).
Repo Metadata Planner
Use these permissions when exporting, previewing, or applying repository names and GitHub custom property values.
Required permissions
| Workflow | Area | Permission | Level |
|---|---|---|---|
| Export / preview | Organization | Custom properties | Read |
| Export / preview | Repository | Metadata | Read |
| Install / update property pack | Organization | Custom properties | Read and write |
| Apply custom property values | Repository | Custom properties | Read and write |
| Apply repository renames | Repository | Administration | Read and write |
repod validates Organization -> Custom properties: Read before export/preview, Organization -> Custom properties: Write before installing the governance property pack, and Repository -> Custom properties: Write before applying non-empty metadata changes.
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.
Important boundary: Members write is also the GitHub permission used for organization invitations and membership changes. repod's Team management feature is intended for teams and team membership, but customers should not grant this mode if their security requirement is "repod's GitHub credential cannot invite organization users."
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.
- Repo Metadata Planner export/preview fails (403): Ensure Organization -> Custom properties: Read.
- Repo Metadata Planner apply fails (403): Ensure Repository -> Custom properties: Write. Repository renames also need Repository -> Administration: Write.
- 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)
- Custom property metadata work -> Fine-grained Organization: Custom properties (read) and Repository: Custom properties (write)
Once PAT scopes are working, continue with our GitHub org permissions governance guide to shape the wider operating model.