Organizations, Teams, Roles, Repository Access, Enterprise Policies, and Delegated Administration: Diagnostics, Failure Modes, Security, and Performance

1. Diagnostic sequence: evidence before revocation guesses

When access looks wrong, use one sequence: preserve evidence → identify repository/org/account/ref/workflow/artifact scope → enumerate every access source → inspect permissions/settings/rules/audit/API responses → choose the least destructive correction → verify effective access again. Do not “fix” access by deleting repositories, rotating unrelated credentials, or making another person owner.

2. Failure: offboarded user retains access through a second path

Suppose devon was removed from app-engineering but still writes app-api. Preserve the original access review output. Inspect direct grants, every team membership, nested parent grants, organization roles, and base permission. In the local fixture, add a second team:

"support-escalation": {"parent": null, "repos": {"app-api":"write"}}

If Devon remains a member of support-escalation, the first team removal was correct but incomplete. The least destructive correction is to remove the stale second membership, not reduce repository permissions for everyone. Then rerun the effective-access evaluator and preserve the before/after evidence.

3. Failure: nested-team inheritance grants more than expected

A child team can inherit all repository grants from every ancestor. If a security-specialist child is moved under a broad Engineering parent with Write across application repositories, that hierarchy change is an authorization change. GitHub warns about repository access when moving teams for this reason.

Repair by changing the parent team's overly broad grant, moving the child to the intended parent, or redesigning hierarchy so parent permissions are safe for every descendant. Do not try to “deny” one child while preserving a stronger inherited parent grant; GitHub permission grants are additive rather than explicit-deny ACLs.

4. Failure: too many organization owners erase separation of duties

If CI admins, security analysts, release engineers, and billing contacts are all owners, every specialist can perform unrelated high-impact operations. There may be no technical evidence distinguishing routine authority from emergency authority. Inventory owners and map each person's actual tasks to narrower repository/team/predefined/custom roles. Retain at least the continuity owners GitHub recommends, but demote unnecessary owners only through a planned, verified change.

5. Failure: base permission creates surprising effective access

A user has no team grant to security-policy but can still read it. If the base permission is Read, this is expected for organization members. Changing the repository's team grants will not remove the base grant. Correct the organization base permission only if the organization's intended policy is different, because changing it affects all existing and future members.

For internal repositories in Enterprise Cloud, even base None does not mean enterprise members lose internal visibility. Diagnose repository visibility before treating read access as a permission leak.

6. Failure: enterprise policy overrides organization settings

An organization owner sees a setting disabled or a REST request rejected and assumes the token lacks scope. Before creating a broader token, check whether the organization belongs to an enterprise with enforced repository, Actions, security, or identity policy. Enterprise owners can define policy that organizations cannot weaken. Under managed users or synchronized teams, the IdP may be authoritative.

The correction is made at the layer that owns the policy—or the organization accepts the inherited constraint. A local workaround that broadens credentials cannot override an enterprise policy and usually increases risk.

7. Intentionally broken offboarding: interpret, do not hide the cause

Use this synthetic state after “offboarding”:

"devon": {
  "active": true,
  "relationship": "member",
  "teams": ["support-escalation"],
  "direct": {"release-ops":"maintain"}
}

The evaluator returns non-none roles. That output is the failure evidence. Do not delete it and replace it with a clean screenshot. Record each source, remove the stale team membership, remove the expired direct grant, then mark the identity inactive/removed in the simulator. The final verification must show none for all repositories. In a live organization, separately verify organization membership/collaborator state and all repository/team paths.

8. Security-sensitive actions and causal risks

9. Reliability and scale: permissions are cached understanding, not static truth

Large organizations can have thousands of membership and repository edges. Avoid N×M API polling when a targeted access review can use team/repository inventories, pagination, audit evidence, or enterprise identity sources. Chapter 26's pagination/rate-limit practices apply. Chapter 27's event-driven patterns can notify a governance service of membership/repository changes, but periodic reconciliation is still needed because event loss, enterprise changes, and external IdP updates can occur.

Knowledge check

Summary

Access diagnosis is source tracing. Hidden second teams, parent inheritance, direct exceptions, base permission, internal visibility, and enterprise policy can all explain “surprising” access. Preserve the original evidence, repair the narrow cause at its authoritative layer, and independently verify effective access rather than relying on the success message from one removal.

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