Skip to content
On this page

Access through teams, not direct collaborators ​

Quarterly access reviews stay manual while direct collaborator grants accumulate. Making team rosters the only path to access turns the review into reading one file:

yaml
collaborators: []

teams:
  - name: platform
    permission: admin
  - name: payments
    permission: maintain
  - name: security-review
    permission: pull

An empty collaborators list is authoritative: apply removes every direct collaborator (the repository owner is never touched), and team-derived access is unaffected because the section manages direct grants only. In check mode the same file emits one drift line per unauthorized direct grant, which is the access review report.

Two caveats complete the picture. The first is that the two sections treat an undeclared entry differently (see the Sections table):

  • Undeclared collaborators are deleted under this file's plain-array declaration (the section's default policy).
  • Undeclared teams holding a direct grant are kept and noted under the section's default. A team you stop declaring keeps its access until removed by hand, or until you set the wrapped teams: {_undeclared: delete, entries: [...]} form, which revokes the direct grants the file does not name.

The second is that pending invitations are reconciled alongside the collaborators, each surfaced as a note:

  • An undeclared pending invitation is cancelled under the same policy (kept as a note under _undeclared: keep).
  • A declared user's pending invitation counts as converged at the declared permission.
  • Only an invitation sent by email, which no username can declare, is left untouched.
Built from main at ab5102dSource: docs/playbooks/teams-not-collaborators.md