How to manage GitHub repo visibility with nested teams using repod

If your target model is “base org access stays minimal and repos are visible through the right teams,” repod is useful after you have decided the GitHub structure you actually want.

This guide shows how to use repod to inspect current repo-team access, clean up broad access paths, and apply a clearer nested-team model with a reviewable diff instead of hand-editing each repository in GitHub.

TL;DR

Problem: the intended nested-team visibility model exists in GitHub, but current repo-team mappings are too broad, inconsistent, or hard to review safely.
Who this is for: GitHub org admins, maintainers, operators, and platform teams cleaning up sensitive repo access.
What this helps you fix: org-wide visibility into repo-team mappings, bulk cleanup of broad access, and delegated review/apply workflows without defaulting to GitHub org admin.

1. Set the policy in GitHub first

repod does not replace GitHub’s base permission settings. Start by deciding the target policy in GitHub itself:

Set base organization repository permissions to the minimum that fits your private-org model.
Define the team hierarchy you actually want GitHub to represent.
Decide which repositories should sit at broad parent-team layers and which should move to narrower child-team layers.
Decide which direct user grants or collaborator paths are genuine exceptions and which should be removed.

repod is strongest once the target access model is clear and the live state is what needs cleanup.

2. Sync the current state into repod

Connect the org with the right PAT scopes and sync it so repod can pull the current repository, team, and repo-team access state into one review surface.

An owner or admin should control the GitHub connection and PAT lifecycle.
Maintainers and operators can then work with the synced access state without needing broader GitHub org admin themselves.

If PAT setup is not done yet, start with GitHub fine-grained PAT guidance for repod.

3. Inspect where access is broader than intended

Before changing anything, look for the common ways a sensitive repo ends up wider than the intended team boundary.

The repo is attached to a parent team when it should sit on a narrower child team.
The repo still has direct team access from an older structure.
The repo carries direct individual grants that bypass the team model.
The team hierarchy is correct in principle, but the actual repo-team mappings no longer reflect it.

This is the point where repod’s org-wide view matters. You are no longer forced to reconstruct the model repository by repository in the GitHub UI.

4. Export the current repo-team mappings

Export the current repo-team access workbook so you have a controlled surface for review and cleanup.

Use the workbook to identify which repositories should move to narrower teams.
Mark stale or overly broad team mappings for removal.
Prepare the target state you actually want before anything is applied back to GitHub.

If your team hierarchy itself is wrong, fix that structure as well. Do not use repo-team mappings to compensate for a permanently broken hierarchy.

5. Review the change set before apply

Import the edited workbook and review the diff carefully.

Check which broad parent-team mappings will be removed.
Check which narrower child-team mappings will be added.
Check whether any permission level changes are wider than expected.
Pause if a sensitive repository still has another broad access path outside the change set.

This is the core operational difference. repod lets you review the access cleanup as one change set instead of relying on memory and many manual clicks.

6. Apply and delegate the day-to-day work

Once the diff matches the intended nested-team model, apply the change set.

Owners and admins keep control of the GitHub connection and higher-risk controls.
Maintainers can manage team hierarchy and assignment workflows.
Operators can run the day-to-day repo-team access workflow without org-level GitHub admin.

That gives you a model where access cleanup can be delegated, but the most sensitive GitHub controls stay tightly held.

7. Edge cases to handle explicitly

Secret teams: useful in narrow cases, but GitHub does not let them participate in nested hierarchy, so do not assume they replace a clean hierarchy or a base-permission decision.
External collaborators: review them separately because they may sit outside the main team model entirely.
Temporary access: track it as an exception with an owner, not a permanent mapping.
Sensitive repos under broad parents: move them down to the right layer rather than accepting broad inheritance forever.