Zyeta Enterprise operations

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

CapabilityTeamUsed by
Repository rules / protected branches on private reposYesprotect-main
Organization rulesetsYes (since June 2025)rulesets/*.json
Code owners + require review from Code OwnersYes.github/CODEOWNERS
Required and multiple PR reviewersYesruleset pull_request rule
Environment deployment branches and secretsYescloudflare-pages, preview
Secret scanning + push protection on private reposYesrepository.json
Validity checks, generic patterns, custom patternsYessecret scanning
CodeQL / code scanning on private reposYessecurity.yml
Dependency review actionYessecurity.yml
SBOM exportYessecurity.yml
Required 2FA, audit log (UI), RBAC, teamsYesPhases 1–2
Actions minutes3,000/month (private)see §7

Not included — plan around these

GapEffect on this designWorkaround
Environment protection rules on private reposOn 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 APIgh 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 reposactions/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 syncNo automatic joiners/leaversManual offboarding checklist (Phase 7)
Custom repository rolesOnly the five fixed roles existMap personas onto read/triage/write/maintain/admin
Merge queue on private reposNot availablestrict_required_status_checks_policy already requires an up-to-date branch
Ruleset evaluate (log-only) modeCannot dry-run a rulesetUse --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:

  1. 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.
  2. Access is granted to teams, never to people. Removing someone from a team removes every repository that team can see, in one action.
  3. 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.

RolePushMerge PRApprove required reviewAct as Code OwnerEdit workflows/secretsManage rulesets & accessDelete 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.

TeamParentPeopleRole on archifyWhy that role
org-admins—2–3 ownersadminOnly team that can change rulesets, environments, access, and the only ruleset bypass
engineering—everyone in engineeringreadBaseline visibility; cannot approve, so it is safe as a parent
platformengineering2–3maintainRuns CI and releases, manages repo settings; not access or rulesets
security—2writeMust approve security-sensitive PRs and dismiss alerts — both need write
ai-agents—nonewriteInstallation 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


4. Traps that cost an afternoon each

TrapWhat happensRule
Team must be visible + write to be a Code OwnerA secret or read-only team in CODEOWNERS is silently ignored; no reviewer is requested and "require Code Owner review" can never be satisfiedOnly write+ visible teams in CODEOWNERS
Child teams inherit, never subtractengineering at write makes every child write; you cannot grant a child lessKeep the parent at the lowest role that is safe for everyone
Secret teams cannot nest and cannot have childrenai-agents as secret would break the hierarchyKeep teams visible (privacy closed)
Teams cannot contain outside collaboratorsA contractor must be an org member (a paid seat) to be on a teamAdd contractors as members with a review date, or as a repo collaborator on a public repo (free)
Deleting a team removes its access everywhereA "cleanup" deletes production accessArchive or empty the team; delete only after verify.sh shows nothing depends on it
Team maintainers manage membership, not accessA team maintainer cannot add a repository to the teamRepository admin or org owner does that
Org owners have admin on every repositoryAdding a fourth owner widens blast radiusKeep 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:

  1. Tag authority as the human gate. protect-release-tags already restricts v* tag creation to OrganizationAdmin (bypass actors). Only an owner can start a release, and that is a recorded, attributable act.
  2. Two approvals on the release PR. Raise required_approving_review_count to 2 for the promotion PR dev → 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

ItemTeamNotes
Seat$4 / user / monthMembers and private-repo outside collaborators
Public repository collaboratorsFree, unlimitedNo seat for a public repo collaborator
GitHub Apps (agents)No seatOne installation, selected repositories
Actions minutes3,000 / month private; free on publicci.yml browser shards are the expensive part
Packages storage2 GBNot 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

  1. Org exists on Team. gh api orgs/$ORG --jq .plan.name → team.
  2. Decide repository visibility — public (recommended: environment reviewers, attestations, free collaborators) or private (see §6).
  3. Base permission none, 2FA required, private-only creation: enterprise/governance/apply.sh --org $ORG --scope org.
  4. Create teams in parent order — org-admins, engineering, platform, security, ai-agents. apply.sh does this; a child cannot be created before its parent.
  5. Transfer or fork the repository into the organization. Teams only apply to organization-owned repositories. A repository under a personal account has no teams.
  6. Grant team roles on the repository (teams.yaml → repositories.archify).
  7. Write CODEOWNERS with teams that have write, and make the CODEOWNERS file itself owned by org-admins.
  8. Apply the rulesets — after the required checks have reported once.
  9. Configure environments and, on a public repo, the production reviewer team.
  10. 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

FileChange
governance/teams.yamlsecurity raised from read to write — approval requires write
governance/org.jsonplan_requirements re-stated for Team, with the three gaps named
.github/workflows/provenance.ymlAttestation skipped with a notice when the repository is private
docs/deployment-runbook.mdPhase 5 environment caveat, Phase 7 audit-log API note, rollback evaluate note
docs/security-controls.mdAudit-log and attestation rows marked plan-dependent