Path rules

Rules on folders: who owns, reads, writes and approves them, and publishing a folder of a private repo.

Markdown

All pages

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.

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:

SettingMeans
Owner groupThe group that owns the path. It can always read and write it, as far as the boundaries above let it.
Approvalrequired: 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 branchesOff by default.
ReadersWho can read the path. Blank means everyone who can read the repo.
WritersWho can change it. Blank means everyone who can read it.

Readers and writers are lists of:

PrincipalMeans
@aliceThe user alice.
@group/opsEveryone in the organization's ops group, or in a group under it. (@team/ops means the same.)
@group/membersEveryone in the organization.
*Everyone who can already read the repo.
@publicEveryone, 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.

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#

ToYou need to be
Change a boundary's settings, readers and writers, or delete itA maintainer of its owner group, or of a group above it
Add a boundary inside one you controlThe same. It can go to that group or any group under it
Give a boundary to a group outside that treeAlso a maintainer of the receiving group
Add a boundary where none covers the pathAn organization owner or admin
Open a path to @publicAn 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:

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:

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:

Branches, commits and diffs stay private. A private repo with public paths isn't listed anywhere; people reach it by direct link.

API#

RequestDoes
GET /api/{owner}/{repo}/boundariesThe 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}/boundariesAdd 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=PThe boundary that owns P
GET /api/orgs/{org}/groupsEvery group, with members and maintainers
POST /api/orgs/{org}/groupsCreate 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.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].