Organizations, Teams, Roles, Repository Access, Enterprise Policies, and Delegated Administration: Concepts, Architecture, and Mental Model

1. The problem: access grows faster than memory

Earlier chapters gave individual repositories controls for reviews, Actions, environments, packages, security findings, APIs, and integrations. Chapter 28 asks who may operate those controls when dozens of repositories and people exist. A repository shared by direct invitations can be understandable at five people and dangerously opaque at five hundred. GitHub organizations add a durable governance layer: people belong to an account, teams represent job functions, repository roles grant capabilities, organization roles delegate administration, and an enterprise account can impose policy above the organization.

The central beginner mistake is to ask only, “Does Alice have access?” Production governance asks a longer question: through which path does Alice have access, at what level, to which resource, because of which organization/team/direct/base/enterprise rule, and who is authorized to change that path? GitHub permissions are commonly additive, so removing one visible grant does not prove access is gone.

2. Mental model: identity → membership → groups/roles → resource → enterprise ceiling

              flowchart TD
                U["GitHub identity"] --> M["Organization membership"]
                M --> T["Teams / nested teams"]
                M --> O["Organization roles"]
                T --> R["Repository roles"]
                M --> B["Base permission"]
                O --> R
                B --> R
                E["Enterprise policy / IAM"] --> M
                E --> R
                R --> X["Effective access"]
                X --> A["Source, settings, Actions, secrets, releases"]
            

The identity is authenticated first. Organization membership determines whether the person is a member, owner, or—in a different relationship—an outside collaborator. Teams group organization members; child teams inherit repository access from parent teams. Organization roles delegate account-wide tasks. Repository roles grant Read, Triage, Write, Maintain, or Admin capabilities. Base permission supplies a floor for organization members across repositories. Enterprise policy and identity-management controls can further constrain what an organization is allowed to configure. The result is effective access: the union of applicable grants, bounded by higher-level policy and product rules.

3. Members, owners, outside collaborators, and managed identities

Authentication and authorization are separate. SAML/SSO, SCIM, or Enterprise Managed Users can control who the identity is and whether it exists, while GitHub organization/team/repository roles control what that identity may do. An IdP group synchronized to a team can make membership authoritative outside GitHub; in that case an API attempt to change synchronized team membership may be rejected because the IdP is the source of truth.

4. Teams, nested teams, and team maintainers

A team is a group of organization members used for repository permissions, review requests, and mentions. A team maintainer can administer many team-level details without becoming an organization owner. This is a useful delegation boundary: the platform team can maintain the platform-engineering membership while organization owners retain account-wide governance.

Nested teams require special care. A child team inherits the parent team's repository access. If Engineering has Write on service-a, then child Payments inherits that Write access. A child can receive additional direct repository grants, but removing its direct grant does not remove inherited parent access. Secret teams cannot participate in nesting. Before changing hierarchy, audit the parent's repository grants because moving a team changes authorization, not merely organization-chart presentation.

5. Repository roles and additive effective access

Organization repositories use five built-in roles from least to most access: Read, Triage, Write, Maintain, Admin. Read supports consumption and discussion; Triage adds issue/PR management without code write; Write permits code contribution; Maintain supports repository management without every sensitive Admin capability; Admin controls repository settings and access. Choose the role from the task, not the person's title.

Access sources are additive. Suppose Noor receives Triage through support, Write through engineering, and the organization base permission is Read. Her effective repository access is at least Write. Removing the support team does not reduce her below Write. This additive behavior is why offboarding must enumerate all paths: direct collaborator grant, every team (including inherited parent-team access), organization-wide role, base permission, and enterprise/internal visibility.

6. Base permission, default-deny, and internal repository visibility

Base permission is the default repository permission for organization members. It does not apply to outside collaborators. A conservative organization usually starts from None for private repositories and grants task-specific access through teams. Changing base permission affects existing and future members, so it is a security-sensitive organization-wide policy change.

7. Delegated administration: predefined and custom roles

Organization ownership is intentionally broad. Delegated administration gives specialists smaller control planes. Current GitHub organization roles include predefined roles such as security manager, billing manager, moderator, and App-management/CI-CD roles depending on product/deployment. The security manager role can grant security specialists read access across repositories plus security-alert/settings capabilities without making them organization owners.

Custom organization roles and custom repository roles provide finer delegation on GitHub Enterprise Cloud (and supported GHES versions). They are not required for this chapter's mandatory path. Custom organization roles can combine organization-setting permissions and, in current Enterprise Cloud capabilities, repository base/additional permissions. Custom repository roles extend a built-in repository role for narrowly scoped repository tasks. Because these features change rapidly, production policy should record the role's exact permissions and review them when GitHub expands the permission catalog.

8. Enterprise policy inheritance, SSO/SCIM/EMU, and scope boundaries

An enterprise account sits above one or more organizations. Enterprise owners can enforce policies that organization owners cannot weaken. A gray/disabled organization control may therefore mean “enterprise policy,” not “you lack organization-owner permission.” Enterprise owners also do not automatically read every organization's content merely because they administer enterprise settings; current Enterprise Cloud lets enterprise owners join an owned organization when needed, creating a distinct organization role.

Enterprise Managed Users goes further: accounts are provisioned and controlled through the identity provider, authentication happens through that IdP, and managed accounts have platform restrictions. This changes onboarding/offboarding: disable/deprovisioning in the identity system may be the authoritative step, while GitHub team/repository assignments still determine resource access. Always distinguish GitHub policy from external identity-provider policy.

9. Repository ownership and transfer are account-boundary changes

An organization-owned repository belongs to the organization account, not to the engineer who created it. Repository Admin can manage the repository, but that is different from owning the organization. A repository transfer moves the repository to another user or organization namespace and can change URLs, access relationships, policy inheritance, Actions/secrets behavior, package relationships, and forks. Transfer is therefore an ownership/governance migration, not an access-cleanup shortcut.

10. Separation of duties, break-glass, onboarding, offboarding, access review

Separation of duties means no routine role gets every capability needed to make and approve a high-impact change. Engineering may write code, security may manage security controls, and release may manage production release gates. Break-glass access is exceptional, time-bounded elevation with a named approver, reason, expiry, and post-event review—not a permanent hidden owner account.

Onboarding should start from the person's job function and team membership. Offboarding should remove authoritative identity access, organization membership or collaborator grants, team memberships, repository grants, deploy/release responsibilities, and credentials owned by or delegated to that person. A periodic access review asks whether every grant still has a current owner, purpose, and expiry. Chapter 29 will turn these decisions into audit and compliance evidence.

11. Read-only inspection first

Before changing an organization, inspect what your current authenticated identity can see. These commands expose names and roles only from organizations you are authorized to inspect; do not paste employer membership data into public logs.

gh auth status
# Your own organization memberships; no mutation.
gh api --paginate -H "X-GitHub-Api-Version: 2026-03-10" user/memberships/orgs   --jq '.[] | {organization:.organization.login,state,role}'

# Optional: only for a disposable organization you administer.
ORG="octo-c28-governance-lab"
gh api -H "X-GitHub-Api-Version: 2026-03-10" "orgs/$ORG"   --jq '{login,default_repository_permission,members_can_create_repositories}'
gh api --paginate -H "X-GitHub-Api-Version: 2026-03-10" "orgs/$ORG/teams"   --jq '.[] | {name,slug,parent:(.parent.slug // null)}'

A 404/403 is evidence to diagnose: the organization may not exist, you may lack membership/permission, enterprise policy may constrain the surface, or the token may not have required organization permissions. Do not respond by creating a broader token before identifying which condition applies.

Knowledge check

Summary

Organization governance is a graph, not a single permission field. Identity and membership feed teams, nested inheritance, direct repository roles, organization roles, and base permission; enterprise policy can constrain the organization from above. Effective access is additive, so least privilege depends on deliberate teams, narrow delegated roles, lifecycle controls, and evidence-based reviews rather than broad ownership or ad-hoc collaborator grants.

Official references

• Roles in an organization
• Managing repository roles
• About organization teams
• Setting base permissions
• Managing custom organization roles
• Repository visibility and internal repositories
• Managed user account abilities and restrictions