Groups decide who can see a repo at all. Inside a repo, path rules (also called ownership boundaries) decide who reads and writes each folder or file, and whose approval a change there needs. A private repo can also publish one folder to the world.
Path rules are set on the server, in the repo's Settings → Access: a table with a row per rule on a folder or file (owner group, who reads, who writes, approval, self-approve), each editable in place, and a last row to add one. Organization owners and admins change them there; a group's maintainers can also change the rules their group owns with oak or the API. They take effect on the next request, and every change is recorded in the organization's audit log with what it was before and after. Nothing about them lives in the repo's files, so a branch can't change the rules that apply to it.
Groups#
A group is a named list of an organization's members, such as eng or billing. Groups can have sub-groups: billing can sit under eng.
- A member of a sub-group counts as a member of every group above it. Anything granted to
@group/engreaches everyone inengand its sub-groups. - A group's maintainers manage it and every group under it: they add and remove members, appoint maintainers and create sub-groups.
- Organization owners and admins manage every group.
- Every organization has the built-in
membersgroup (everyone in it), andpublic(anyone), which path rules spell@public. Nobody is added to any other group automatically.
Groups are managed from each repo's Settings → Access (the organization's Settings → Groups lists them all), with oak group, or with the API.
Boundaries#
A boundary is a path of one repo — a directory, or a single file — with:
| Setting | Means |
|---|---|
| Owner group | The group that owns the path. It can always read and write it, as far as the boundaries above let it. |
| Approval | required: a change needs the owner group's approval before it merges. advisory: the branch shows the approval is wanted, but it doesn't block. off: neither. |
| Owners may approve their own branches | Off by default. |
| Readers | Who can read the path. Blank means everyone who can read the repo. |
| Writers | Who can change it. Blank means everyone who can read it. |
Readers and writers are lists of:
| Principal | Means |
|---|---|
@alice | The user alice. |
@group/ops | Everyone in the organization's ops group, or in a group under it. (@team/ops means the same.) |
@group/members | Everyone in the organization. |
* | Everyone who can already read the repo. |
@public | Everyone, including people with no access to the repo at all. |
| (an empty list) | Organization owners and admins only. |
Owners and admins always have full access, whatever the boundaries say.
A repo with no boundaries has no path rules, and nothing waits for an approval.
Nested boundaries#
A path belongs to its deepest boundary.
- Ownership and approval come from that boundary alone.
- Access only narrows going down. You can read a path only if every boundary above it lets you read. A nested boundary can lock its path down further, but it can't reopen what an enclosing boundary closed.
@publicis the exception: a boundary that names it opens its path to everyone, whatever encloses it. Only organization owners and admins can set it.
A boundary on a directory covers it and everything in it. A boundary on a file covers just that file: one on config/prod.yaml restricts that file, not config/prod.yaml.bak next to it. Boundaries are exact paths, not patterns: *.pem or secrets/** is refused.
Who can change boundaries#
| To | You need to be |
|---|---|
| Change a boundary's settings, readers and writers, or delete it | A maintainer of its owner group, or of a group above it |
| Add a boundary inside one you control | The same. It can go to that group or any group under it |
| Give a boundary to a group outside that tree | Also a maintainer of the receiving group |
| Add a boundary where none covers the path | An organization owner or admin |
Open a path to @public | An organization owner or admin |
So the maintainers of eng can split apps/ among eng's sub-groups, and each sub-group's maintainers can split their own directory further.
Changing boundaries also takes write access to the repo, as any other change to it does.
Changing a boundary's owner group or approval setting clears the approvals branches already had for it.
Approvals#
A branch's touched boundaries are the deepest boundary of each file it changes. Each required one needs an approval from someone on its owner group who didn't work on the branch, before the branch can merge. An approval lasts as long as that boundary's part of the change stays the same: editing elsewhere, or merging main in, keeps it.
Approve on the branch page, or with oak approve and an API key that has the Review scope (Settings → API keys). oak approve --path apps/web approves one boundary. oak owners --branch shows what a branch needs.
Organization owners and admins can land a branch past missing approvals, as the repo's Forcing past approvals setting allows (Settings → Access).
Restricted paths#
For someone who can read the repo, a path no boundary restricts is readable, and boundaries take access away.
What a restricted path looks like to someone without access:
- You get a partial checkout.
oak clone,oak pullandoak log --remoteserve you the repo without the directories you can't read: they aren't in the tree at all, not even by name (see below). - The web UI, zip downloads and Pages sites leave restricted entries out entirely.
- Writes are refused. A push, upload or revert that changes a path you may not write is rejected. Merging
maininto your branch withoak pullis fine — carrying the restricted files along unchanged isn't a write. - Branches are hidden. A branch that changes a directory you can't read is hidden from you, because its description could say what's there.
- If identical content also lives at a path you can read, you can read those bytes there.
If you can't read some directories#
Every commit on main carries its message, author and the names of the files it changed, and its hash covers all of that, so a commit can't be served with part of it removed. If any directory is restricted from you, Oak therefore serves you main only as a partial checkout (a view): the same commits rebuilt without the directories you can't read. A commit that also changed one of them keeps its author and date, but its message reads "(also changes paths outside your view)".
The CLI does this for you:
oak clone ORG/REPOnotices that some directories are hidden from you and clones the rest.oak sparse showlists what you have;oak clone ORG/REPO --path DIRstill clones only the directories you name.- In a full checkout you made before a directory was restricted,
oak pullturns it into a partial checkout and then pulls. That needs nothing local to lose, so commit andoak pushyour work first; until thenoak pullstops and says so. oak log --remotereadsmain's history through the same partial view. In a full checkout it reads commit metadata instead, leaving out the commits that changed a directory you can't read, as the History page does.
Organization owners and admins, and anyone who can read every directory, keep getting the full repo.
Older oak versions get a refusal instead (HTTP 403 with "code": "view_required") that tells you to run oak upgrade, or to clone the directories you need with oak clone ORG/REPO --path DIR. GET /api/{owner}/{repo}/boundaries reports view_required up front, for scripts that talk to the API directly; send the view with ?view_protocol=view_v1&view=%2B (the whole repo) or the oak-view-* headers.
Publishing paths with @public#
@public runs the other way, for people who have no access to the repo. For them, a path is hidden unless a boundary grants it to @public. That's how one private repo can contain a genuinely open-source directory — and it fails safe: forget a boundary, and too little is published, never too much.
Outsiders can read a published directory:
- in the web UI: the file tree, the file view and the zip download.
Branches, commits and diffs stay private. A private repo with public paths isn't listed anywhere; people reach it by direct link.
API#
| Request | Does |
|---|---|
GET /api/{owner}/{repo}/boundaries | The boundaries whose paths you can read, plus view_required (some directory is hidden from you, so main is served to you only as a partial checkout) and hidden_directories |
POST /api/{owner}/{repo}/boundaries | Add one: {"path", "owner_group", "approval"?, "self_approve"?, "readers"?, "writers"?} |
PATCH /api/{owner}/{repo}/boundaries/{id} | Change one; readers/writers take null for the default |
DELETE /api/{owner}/{repo}/boundaries/{id} | Delete one |
GET /api/{owner}/{repo}/owners?path=P | The boundary that owns P |
GET /api/orgs/{org}/groups | Every group, with members and maintainers |
POST /api/orgs/{org}/groups | Create one: {"slug", "parent"?, "description"?} |
PATCH /api/orgs/{org}/groups/{group} | Change its description or parent |
DELETE /api/orgs/{org}/groups/{group} | Delete one with no sub-groups and no boundaries |
PUT /api/orgs/{org}/groups/{group}/members/{user} | Add someone, or change {"maintainer": true} |
DELETE /api/orgs/{org}/groups/{group}/members/{user} | Remove someone |
From the CLI: oak access, oak owners PATH, oak group list|show|create|add|remove|invite, and oak groups for the groups you're in. Repo access for groups is on Organizations and access.