Team-based access model
How access works on this organization at GitHub Team ($4 per user per month), who gets what, and the exact steps to grant or remove it.
Verified against GitHub's pricing page, rulesets docs, environments docs, CODEOWNERS docs and the repository-roles permission matrix on 2026-11-03. Plan features move; re-check the three plan-dependent items in §1 before promising them.
1. What the Team plan actually gives you
Team is enough for almost everything this repository needs. Three things are not included, and one of them silently removes a control rather than blocking it.
Included and load-bearing for us
| Capability | Team | Used by |
|---|---|---|
| Repository rules / protected branches on private repos | Yes | protect-main |
| Organization rulesets | Yes (since June 2025) | rulesets/*.json |
| Code owners + require review from Code Owners | Yes | .github/CODEOWNERS |
| Required and multiple PR reviewers | Yes | ruleset pull_request rule |
| Environment deployment branches and secrets | Yes | cloudflare-pages, preview |
| Secret scanning + push protection on private repos | Yes | repository.json |
| Validity checks, generic patterns, custom patterns | Yes | secret scanning |
| CodeQL / code scanning on private repos | Yes | security.yml |
| Dependency review action | Yes | security.yml |
| SBOM export | Yes | security.yml |
| Required 2FA, audit log (UI), RBAC, teams | Yes | Phases 1–2 |
| Actions minutes | 3,000/month (private) | see §7 |
Not included — plan around these
| Gap | Effect on this design | Workaround |
|---|---|---|
| Environment protection rules on private repos | On a private repo, the production environment may be creatable with secrets and branch policies, but Required reviewers is a public-repo feature on Team. The release gate disappears — silently. | Keep the repo public (it is Apache-2.0), or gate releases on tag authority instead — see §6. |
| Audit log API | gh api orgs/<org>/audit-log returns 404. The incident-preservation command in the runbook cannot run. | Review in the UI (Org Settings → Logs), export manually, or move to Enterprise when audit retention matters. |
| Artifact attestations on private repos | actions/attest-build-provenance cannot run. provenance.yml now skips it with a notice and still publishes SHA256SUMS.txt. | Public repo, or Enterprise. |
| SAML SSO, SCIM, team sync | No automatic joiners/leavers | Manual offboarding checklist (Phase 7) |
| Custom repository roles | Only the five fixed roles exist | Map personas onto read/triage/write/maintain/admin |
| Merge queue on private repos | Not available | strict_required_status_checks_policy already requires an up-to-date branch |
Ruleset evaluate (log-only) mode | Cannot dry-run a ruleset | Use --dry-run in apply.sh, or apply to one repository first |
[object Object]
2. The model in one picture
Organization (base permission: none)
│
├── org-admins ......................... admin → everything, only bypass actor
├── engineering ........................ read → sees code, cannot approve or push
│ ├── platform ....................... maintain → CI, releases, repo settings
│ ├── backend ........................ write → pushes and approves
│ ├── frontend ....................... write
│ └── mobile ......................... write
├── security ........................... write → must be write to approve PRs
└── ai-agents .......................... write → no people, GitHub Apps only
Three rules produce that shape:
- Base permission is
none. A member sees nothing until a team grants it. There is no "everyone can read by default" floor to leak a repository. - Access is granted to teams, never to people. Removing someone from a team removes every repository that team can see, in one action.
- Approval requires
write. This is the part most people get wrong — see below.
The permission that decides everything: who can approve
From GitHub's repository-role matrix, "Approve or request changes to a pull request with required reviews" requires write or higher. A read or triage member can comment, review informally, and request changes — but their approval does not satisfy the ruleset.
So "read-only reviewer" is not a thing on GitHub. If someone must approve, they need write, and write also means they can push to unprotected branches.
| Role | Push | Merge PR | Approve required review | Act as Code Owner | Edit workflows/secrets | Manage rulesets & access | Delete repo |
|---|---|---|---|---|---|---|---|
read | — | — | — | — | — | — | — |
triage | — | — | — | — | — | — | — |
write | ✓ | ✓ | ✓ | ✓ | ✓ | — | — |
maintain | ✓ | ✓ | ✓ | ✓ | ✓ | — | — |
admin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
maintain adds repository settings (description, topics, merge settings, wiki, Pages source). It still cannot manage access, rulesets, webhooks, or delete.
3. Team roster and repository roles
This is the desired state in ../governance/teams.yaml, applied by apply.sh --scope org.
| Team | Parent | People | Role on archify | Why that role |
|---|---|---|---|---|
org-admins | — | 2–3 owners | admin | Only team that can change rulesets, environments, access, and the only ruleset bypass |
engineering | — | everyone in engineering | read | Baseline visibility; cannot approve, so it is safe as a parent |
platform | engineering | 2–3 | maintain | Runs CI and releases, manages repo settings; not access or rulesets |
security | — | 2 | write | Must approve security-sensitive PRs and dismiss alerts — both need write |
ai-agents | — | none | write | Installation target for GitHub Apps; holds no humans |
frontend, backend, mobile appear in the org-level template for other repositories. They do not exist for archify until there is more than one codebase; adding empty teams creates the illusion of structure.
Where each role stops
platformcannot configure environments. Only repository admin can. That is deliberate: environment configuration is done byapply.shwith an owner token, and a maintainer cannot quietly add a reviewer-less environment.securitycan push. Accepted, because the alternative — read-only — cannot approve. Theprotect-mainruleset still stops a direct push tomain.engineeringcannot approve. If someone needs to approve, move them into the area team. Do not raise the parent team's role; that would grant approval to everyone at once.
4. Traps that cost an afternoon each
| Trap | What happens | Rule |
|---|---|---|
| Team must be visible + write to be a Code Owner | A secret or read-only team in CODEOWNERS is silently ignored; no reviewer is requested and "require Code Owner review" can never be satisfied | Only write+ visible teams in CODEOWNERS |
| Child teams inherit, never subtract | engineering at write makes every child write; you cannot grant a child less | Keep the parent at the lowest role that is safe for everyone |
| Secret teams cannot nest and cannot have children | ai-agents as secret would break the hierarchy | Keep teams visible (privacy closed) |
| Teams cannot contain outside collaborators | A contractor must be an org member (a paid seat) to be on a team | Add contractors as members with a review date, or as a repo collaborator on a public repo (free) |
| Deleting a team removes its access everywhere | A "cleanup" deletes production access | Archive or empty the team; delete only after verify.sh shows nothing depends on it |
| Team maintainers manage membership, not access | A team maintainer cannot add a repository to the team | Repository admin or org owner does that |
| Org owners have admin on every repository | Adding a fourth owner widens blast radius | Keep owners at 2–3; delegate with the Security manager / CI-CD admin org roles instead |
5. Personas → exact steps
Run as an org owner. $ORG is your organization slug.
New engineer
gh api -X PUT "orgs/$ORG/teams/engineering/memberships/<login>" -f role=member
gh api -X PUT "orgs/$ORG/teams/backend/memberships/<login>" -f role=member # write on their repos
They can read every repository engineering can see, push and approve on backend repositories, and cannot merge to main without a second approval.
Reviewer / senior engineer
Same as above — do not create a "reviewers" team. Approval follows from write on the area team, and a separate reviewers team would be a second, drifting source of truth.
Platform on-call
gh api -X PUT "orgs/$ORG/teams/platform/memberships/<login>" -f role=member
maintain on the repository, main role in the platform team so they can manage rota membership themselves. They can re-run workflows and publish a release once the production reviewer approves.
Security reviewer
gh api -X PUT "orgs/$ORG/teams/security/memberships/<login>" -f role=member
write, plus the Security manager organization role if it is offered on your plan (Org Settings → People → Roles). Security manager grants alert and policy management without repository administration — verify it appears before relying on it; custom organization roles are Enterprise-only.
Contractor
Public repository: add as an outside collaborator on read — no seat, no team membership, no access to anything else.
gh api -X PUT "repos/$ORG/archify/collaborators/<login>" -f permission=pull
Private repository: outside collaborators consume a $4 seat. Prefer a time-boxed team membership with a review date recorded in the access log.
AI agent
Never a person, never a PAT. Create a GitHub App, install it on selected repositories, and grant it through ai-agents:
gh api orgs/$ORG/installations --jq '.[] | {app: .app_slug, selection: .repository_selection}'
Agents consume no seats — that is one reason to prefer an App over a bot account.
Product, design, finance
read via engineering if they are engineers; otherwise a triage-only team for issue management. Do not grant write to someone who will never push.
Leaver
gh api -X DELETE "orgs/$ORG/members/<login>"
gh api "orgs/$ORG/teams" --jq '.[].slug' | while read -r t; do
gh api -X DELETE "orgs/$ORG/teams/$t/memberships/<login>" 2>/dev/null || true
done
Then revoke tokens/SSH keys, rotate any shared secret they could read (secrets-inventory.yaml says which), and record the date.
6. If the repository must stay private
On Team + private, the production environment cannot require reviewers. Keep the same outcome with two other controls:
- Tag authority as the human gate.
protect-release-tagsalready restrictsv*tag creation toOrganizationAdmin(bypass actors). Only an owner can start a release, and that is a recorded, attributable act. - Two approvals on the release PR. Raise
required_approving_review_countto 2 for the promotion PRdev → main, so the code being released has two humans behind it.
Then record the deviation in the phase record:
Deviations: production environment has no required reviewers — Team plan, private repo.
Compensating controls: tag creation restricted to org-admins; 2 approvals on release PR.
Owner: platform. Revisit on Enterprise upgrade or if the repo becomes public.
verify.sh will keep reporting the missing reviewer as drift. That is correct: an accepted risk should stay visible, not be silenced.
7. Cost model
| Item | Team | Notes |
|---|---|---|
| Seat | $4 / user / month | Members and private-repo outside collaborators |
| Public repository collaborators | Free, unlimited | No seat for a public repo collaborator |
| GitHub Apps (agents) | No seat | One installation, selected repositories |
| Actions minutes | 3,000 / month private; free on public | ci.yml browser shards are the expensive part |
| Packages storage | 2 GB | Not used by this repository |
At 8 people that is $32/month. The pipeline's own cost is the risk: a full regression with two browser shards, two WebM jobs and a three-OS package smoke can consume 40–80 minutes per run. Thirty full runs in a month approaches the 3,000-minute allowance — which is exactly why ci-scope.mjs classifies docs-only and core changes instead of running everything. Do not "fix" a slow pipeline by removing the classifier.
8. Setup sequence
- Org exists on Team.
gh api orgs/$ORG --jq .plan.name→team. - Decide repository visibility — public (recommended: environment reviewers, attestations, free collaborators) or private (see §6).
- Base permission
none, 2FA required, private-only creation:enterprise/governance/apply.sh --org $ORG --scope org. - Create teams in parent order —
org-admins,engineering,platform,security,ai-agents.apply.shdoes this; a child cannot be created before its parent. - Transfer or fork the repository into the organization. Teams only apply to organization-owned repositories. A repository under a personal account has no teams.
- Grant team roles on the repository (
teams.yaml→repositories.archify). - Write CODEOWNERS with teams that have write, and make the CODEOWNERS file itself owned by
org-admins. - Apply the rulesets — after the required checks have reported once.
- Configure environments and, on a public repo, the
productionreviewer team. - Verify:
gh api orgs/$ORG --jq '{plan: .plan.name, base: .default_repository_permission, tfa: .two_factor_requirement_enabled}'
gh api orgs/$ORG/teams --jq '.[] | {slug, parent: .parent.slug}'
gh api orgs/$ORG/teams/security/repos/$ORG/archify --jq .permission # write
gh api orgs/$ORG/teams/ai-agents/members --jq 'length' # 0
gh api repos/$ORG/archify/environments/production --jq '.protection_rules'
enterprise/governance/verify.sh --org $ORG --repo $ORG/archify
9. What changed in this repository because of the Team plan
| File | Change |
|---|---|
governance/teams.yaml | security raised from read to write — approval requires write |
governance/org.json | plan_requirements re-stated for Team, with the three gaps named |
.github/workflows/provenance.yml | Attestation skipped with a notice when the repository is private |
docs/deployment-runbook.md | Phase 5 environment caveat, Phase 7 audit-log API note, rollback evaluate note |
docs/security-controls.md | Audit-log and attestation rows marked plan-dependent |