# Groups

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](/docs/path-permissions) name groups as the owners, readers and writers of folders. The organization's own [agents](/docs/api-keys#organization-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](/docs/api#account-and-keys)).

## 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

```bash
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:

```bash
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](/docs/organizations#who-can-see-a-repository).

## Folders

Inside a repo, [path rules](/docs/path-permissions) 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](/docs/api-keys#organization-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.

```bash
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](/docs/api-keys#keys-for-agents) 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.
