GitHub Teams: hierarchy, repository access and permissions

GitHub Teams should make repository access easier to explain: which team owns a repo, which permission it has, and which access a child team inherits from its parent.

Practical default

Keep the hierarchy shallow and attach access deliberately

• Child teams inherit repository access from parent teams.
• Give a parent only the permissions that are safe for every child.
• Add narrower or higher access lower in the hierarchy where it is needed.

How GitHub Team hierarchy affects repository access

A child team receives repository access granted to its parent. A direct grant to the child can add access for a narrower group without widening the parent. Effective permission can therefore come from more than one place.

• Parent grant: inherited by every child team below it.
• Direct child grant: applies to that child and its descendants.
• Effective permission: the strongest access available after direct and inherited paths are considered.
• Removing inherited access: requires changing the parent source; the child cannot discard it alone.

Worked inheritance example

1. Parent team Engineering Read on service-catalog
2. Inherited access Platform Inherits Read on service-catalog
3. Direct child grant Platform Write on deployment-controller

Team	Repository	Grant source	Effective access
Engineering	service-catalog	Direct Read grant	Read
Platform	service-catalog	Inherited from Engineering	Read
Platform	deployment-controller	Direct Write grant	Write

Platform reads service-catalog because its parent can. It writes to deployment-controller because that narrower grant is attached directly to Platform. Removing the inherited access requires changing the grant on Engineering.

What GitHub Teams should represent

Teams are both collaboration groups and the normal unit for repository permissions. A useful team model answers an ownership question: which group operates this repository, and what level of access does that group need?

Keep universal membership separate from ownership. An everyone team should normally sit alongside departments and contractors, not above every other team where its permissions would cascade through the company.

everyone
engineering
+-- engineering-platform
+-- engineering-backend
`-- engineering-frontend
product
operations
security
contractors

Nest squads or specialties under real departments and domains. Shallow hierarchy usually beats a complete-looking org chart that nobody can audit without tracing a long inheritance chain.

Repository roles and where to assign them

Role	Typical use	Review signal
Read	People who need to inspect code without changing it.	Is broad visibility intentional for this repository?
Triage	Issue and pull-request coordination without push access.	Would Triage meet the need instead of Write?
Write	Day-to-day contributors who push code.	Does the team actively contribute to this repository?
Maintain	Maintainers responsible for repository operations.	Can the responsibility be explained and reviewed?
Admin	Rare owners or platform cases needing full control.	Is destructive and security-sensitive access justified?

If a person has a recurring direct grant that mirrors a role, turn that pattern into a team. The GitHub Direct access vs Organization access guide explains that decision in detail.

GitHub Teams audit checklist

1. List every parent team with repository access.
2. Confirm each parent grant is safe for all child-team members.
3. Trace Maintain and Admin access back to its direct or inherited source.
4. Move narrower access to the child or ownership team that actually needs it.
5. Keep contractors and vendors out of broad employee groups by default.
6. Replace recurring direct-user exceptions with a team where the role is durable.

Common GitHub Teams questions

Review the live hierarchy before changing it

repod shows team structure, inherited and direct repo mappings, high-privilege teams, and uncovered private repositories in one place before you apply changes.

Run Free Audit See what the audit checks

Related guides

• Private GitHub repository visibility
• GitHub repository permissions audit checklist
• GitHub governance and permission drift guide

Sources

• About organization teams
• Managing team access to an organization repository
• Repository roles for an organization