A group is a named list of an organization's people, such as eng or billing. Access to repos is given to groups, and path rules name groups as the owners, readers and writers of folders. The organization's own agents can be on groups too.
In the web UI, groups are under the organization's Settings → Groups (oak.space/<org>/settings): one card per group, with its members, maintainers, agents and what it reaches. What a group can do in one repo is set in that repo's Settings → Access. From the terminal it's oak group, and over the HTTP API it's /api/orgs/{slug}/groups (see the API reference).
Built-in groups#
Every organization has two groups it can't delete:
| Group | Who's in it |
|---|---|
public | Anyone, signed in or not. Giving it Read on a repo makes the repo public. It can't be given Write. |
members | Everyone in the organization. Adding someone to members adds them to the organization, and removing them takes them out of it and every group. |
Who is in a built-in group follows from the organization, so neither can be nested or take agents. Every other group is one you create, and nobody is added to it automatically.
Creating groups and adding people#
oak group create web --description "Web app"
oak group add web alice
oak group add web bob --maintainer
oak group invite web carol # adds carol to the organization first if needed
oak group list # every group, as a tree
oak group show web # parent, maintainers, members, repos
oak groups # the groups you're in
Organization owners and admins manage every group. A group's maintainers manage it and every group under it: they add and remove members, appoint maintainers and create sub-groups. Inviting someone who isn't in the organization yet takes an owner or admin. Anyone can remove themselves from a group.
Nested groups#
A group can sit under another: oak group create billing --parent eng. Someone in billing counts as a member of eng too, so anything given to eng reaches everyone in billing. Maintainers go the other way: a maintainer of eng also maintains billing.
A top-level group takes an owner or admin to create; a sub-group takes a maintainer of the group above it.
Giving a group access to a repo#
Give a group Read or Write on a repo, and everyone in it (and in its sub-groups) gets that:
oak group grant web acme/site --role write
oak group revoke web acme/site
oak group grant public site # make the repo public
The same table is in the repo's Settings → Access, with a row per group or person and a Read or Write picker on each. Granting repo access takes an organization owner or admin, who can always read and write every repo themselves. See Who can see a repository.
Folders#
Inside a repo, path rules narrow access to folders and files by group: a rule's owner group approves changes there, and its readers and writers can be @group/name. Rules are edited in the repo's Settings → Access, under the grants.
Agents on groups#
An organization's agents are its own non-human accounts, created under Settings → Agents. An agent reaches what the groups it's on reach, never its creator's access. A new agent is on no group, so it reaches only public repos.
oak group agent list # each agent and its groups (owners and admins)
oak group agent add web deploy-bot
oak group agent remove web deploy-bot
Adding an agent takes a maintainer of the group, or an owner or admin. In the web UI, add one from the group's card under Settings → Groups. A person can also give an agent a key that works as a group without creating an organization agent.
Working as a group#
oak group switch web makes your checkout work as web: you see and change exactly what the group can, until oak group switch --clear. It uses a 30-day key whose grant is the group, for that checkout only. oak group switch with no name says which group the checkout works as, and oak groups marks it with *. It's a way to check what a group's people and agents get.