Access control and the principle of least privilege

Least privilege is easy to agree with and hard to keep. The permission list of a five-year-old infrastructure repository is usually a historical record of everyone who has ever been adjacent to the project, and the reason is structural: access is granted at the moment of need, under time pressure, and removed at no moment in particular. This lesson is about the grants themselves and the review that removes them.

The role ladder

Both major forges expose a small ladder of repository roles. The names differ; the operational distinctions are close:

Two boundaries matter more than the rest. The first is between read and write: write is the ability to place code in the repository, and everything downstream - CI runs, review requests, protection rules - exists to constrain what happens after that placement. The second is between maintain and admin: admin is the ability to change the constraints themselves, including turning off branch protection.

Teams, not people

Granting access to an individual creates a permission that belongs to a person, which means it has no lifecycle. Nobody knows why alice has write on infra-prod; the grant outlives the project that justified it.

Granting access to a team creates a permission that belongs to a role, and the lifecycle comes for free: joining the platform team confers the access, leaving it removes the access, and the answer to “why does this person have write?” is “because they are on the team that owns this repository”.

flowchart TD
    A["identity provider group"] --> B["forge team: platform-oncall"]
    B --> C["repo: infra-prod (write)"]
    B --> D["repo: infra-modules (write)"]
    E["individual grant: alice (admin)"] -.->|"no lifecycle, no owner"| C
    F["offboarding"] --> A
    F -.->|"misses"| E

The dotted edges are where audits find the problem: the individual grant survives the offboarding process because the offboarding process removes group membership, and the grant was never a group membership.

Machine identities are not small humans

A pipeline, a bot, and a deploy key are identities too, and they should be scoped harder than humans because they are unattended:

• Deploy keys attach to one repository. Make them read-only unless the pipeline genuinely writes back; a read-only deploy key that leaks is a disclosure, a read-write one is a supply-chain event.
• Tokens should carry the narrowest scope and the shortest life the job tolerates. A token that can read one repository is not the same risk as a token that can administer an organisation.
• Forge apps are usually the right answer at scale: permissions are declared, installation is per-repository, and the credential is short-lived by construction.

REPO=example-org/infra-prod
gh api "repos/$REPO/collaborators" \
  --jq '.[] | [.login, .role_name] | @tsv'

The review that actually removes access

A workable cadence for an infrastructure repository:

1. Quarterly, list every principal with write or above, including bots, deploy keys, and outside collaborators.
2. Cross-check against the identity provider. Anyone not in an owning group is a finding, not a discussion.
3. Revoke first, restore on request. Restoration is cheap and instantaneous; standing access is neither.
4. Record the review with a date and the revocation count. A review with no artefact did not happen, and an auditor will treat it that way.

Production discipline

1. Default to read. Write is granted for a named piece of work by someone accountable, and the grant is recorded.
2. No individual grants on production repositories. If a person needs access, the team they are on needs access, or they should join the team that has it.
3. Machine identities get a named owner and an expiry. An unowned token with no expiry is the credential that will still be valid three years after the service it served was decommissioned.

Cross-course references

• Ansible for Production Sysadmins - the inventory and vault parts depend on exactly which identities can read the repository that holds them.
• Terraform for Production Sysadmins - state backend permissions and repository permissions must be reasoned about together; write on the repo plus apply in the pipeline is a single privilege path.
• Kubernetes for Production Engineers - RBAC roles and bindings are the same modelling problem one layer down.

Quiz