Marks

Named pointers to commits on main that people and bots move, and that deploy machines follow.

Markdown

All pages

A mark is a named pointer to a commit on main, one for each thing you deploy or release: server-prod for what oak.space runs, cli for the newest CLI commit whose tests passed. A machine follows the mark. When main changes the mark's folders it runs your check, moves the mark when the check passes, and deploys the move. So the mark always points at the last commit that passed and went out, and the reports on the commits after it say why they didn't.

Oak runs none of your code for this. The checks and the deploys run on your machines, and the mark is how they hand a commit to each other.

Who can do what#

A thing that needs a person to sign off before it goes out gets an owner group of the people who sign off, and a follower with only --run: it deploys what they move the mark to.

Create, move, roll back#

oak mark create web --path services/web --path libs/ui --owner-group web --follower web-deploy
oak mark move web main                 # main's head
oak mark move web 3f2a8b1c --note "ship the new cache"
oak mark rollback web 1d9e0c77         # an earlier commit
oak mark list
oak mark show web
oak mark log web

A mark starts at main's head unless you pass --commit. Creating a mark deploys nothing: its first move carries no grant and followers skip it. Commits are main, a full hash, or a unique prefix of at least seven characters. Every oak mark command takes --repo OWNER/NAME (default: the checkout's repository), -r, --remote URL and --json.

The rules a move has to pass:

--root NAME makes a mark point into a root instead of main; the same rules apply along the root's history.

Folders#

A mark names the folders (or files) of main it is about with --path (repeatable; oak mark paths MARK PATH... changes them later, repo admins). Whenever main's head holds something different under those paths than the mark's commit, its followers hear about it: a change. Oak decides what changed from the tree hashes of the paths, so two commits with the same files under them count as the same however far apart they are, and changes elsewhere in the repository never wake a follower. Name every folder the build reads: a change to a folder the mark doesn't list won't rebuild it. A mark without paths covers the whole repository. oak mark list --changed lists the marks whose folders hold something new at main's head.

Following a mark#

oak mark follow web --repo acme/monorepo --check scripts/test.sh --run scripts/deploy.sh

oak mark follow does two jobs, one per script:

Give both for a thing that deploys, only --check for one that only needs the newest commit that passed (a daily release reads the mark's commit), and only --run for one a person moves by hand. Moving the mark takes a credential that may move it, so a follower with --check usually runs as an organization agent on the mark's owner group, with the release scope when the mark is protected. That key lives on the machine that follows, so the people and agents who merge never need release rights of their own.

The follower files reports on each commit under the mark's name (--report-name picks another): "checking (change)", then "passed" or "failed (change)"; and for a deploy "deploying (move #12 by zach)", then "live (move #12)" or "failed (move #12)", each followed by the end of the script's output. Arguments for the --run script go after --.

It handles one event at a time. If several land while a script runs, only the newest runs next. What it handled is kept in a state file (--state-file, default <dir>.follow.json), so a restart carries on from there; a move or change that was running when the follower stopped is reported failed and not run again (move the mark again to retry a move). --once handles at most one event and exits, which suits a cron job or a test. --no-checkout runs the scripts without checking anything out. Run it as one of the mark's followers so --run gets the grant; anyone else gets moves without it, and oak mark follow stops with an error unless you pass --no-grant.

The check runs with:

VariableWhat
OAK_COMMITmain's head
OAK_EVENTchange
OAK_MARK, OAK_MARK_PATHSThe mark, and its paths one per line
OAK_INPUTSA hash of what is under the paths
OAK_REPO, OAK_REMOTE, OAK_LINEThe repository, the server, and main
OAK_REPO_IDThe repository's numeric id (followers only)

The deploy runs with:

VariableWhat
OAK_COMMITThe commit the mark moved to
OAK_EVENTmove
OAK_MARK, OAK_MOVE_ID, OAK_MOVE_KINDThe mark, the move's id, and create, forward or rollback
OAK_REPO, OAK_REMOTEThe repository and server
OAK_LINEmain, or ~NAME for a mark on a root
OAK_REPO_IDThe repository's numeric id (followers only)
OAK_GRANT, OAK_GRANT_SIGNATUREThe move's signed grant and its minisign signature, both base64, when the server signs grants (followers only)

The grant names everything about the move a target needs to check (see Signed moves), so a script reads the rest from it. The older OAK_CI_* names are still set for deploy scripts written before these, and are deprecated. Secrets stay on the machine that follows: put them in its environment, not in Oak.

Many marks on one machine#

One follower can follow every mark whose name matches a pattern (* stands for any run of characters), in one request to the server however many marks match:

oak mark follow --match 'web-*' --repo acme/monorepo --check scripts/test.sh --run scripts/deploy.sh --jobs 8

Each mark gets its own work dir under --dir (./oak-marks/<MARK> by default) and its own reports, up to --jobs scripts run at once, and one failing doesn't hold up the others. A mark it starts following isn't checked or deployed until it moves or changes again.

Pausing and rolling back#

To hold a mark, pause it: its followers stop getting change events until it's resumed, and moving or rolling it back by hand still works. A rollback of a mark with paths pauses it too, so the next change doesn't deploy straight over it.

oak mark pause web --note "bad cache config"
oak mark rollback web 1d9e0c77
oak mark resume web

Signed moves#

When the server has a release grant key, every move (but a mark's first) gets a grant signed with it: a short document naming the repository, the commit, the move and a single-use authorization id, valid for four hours. The identity it names is fixed when the move is made, so changing a mark later never changes an old move's grant. A follower asking for an expired grant gets it signed again only while the move is the mark's current one and less than a day old; after that the mark has to be moved again (the same commit is fine). A target that holds the public key can check that a commit really was moved there before it acts on it, and refuse a grant it has seen before. The grant is plain key=value lines:

schema=oak-release-grant-v1
repo_id=42
source_commit=<the commit>
branch=main
workflow_path=.oak/marks/server-prod
workflow_hash=<a hash of the mark>
event=manual
ci_run_id=<the move's id>
authorization_id=<single use>
environment_id=<the mark's id>
environment_name=server-prod
policy_version=<the mark's policy version>
issued_at=<unix seconds>
expires_at=<unix seconds>

The field names come from Oak's old CI and stay as they are, so a target that already checks these grants keeps working. A mark can instead carry a fixed identity that a target pins, which its grants then name exactly; that is set through the API, and the CLI doesn't offer it.

Reports#

A mark's follower files reports on the commits it checks and deploys, and anyone can file their own with oak report: what the tests said, a deploy's log, a review.

On the web#

Marks show on the History tab. Each commit's line starts with its marks, the same width on every line so they line up: the first mark (your own groups' first, then the most recently moved), in its owner group's colour, and +N for the rest, which opens the commit's page with every mark there. A mark's name opens its moves with who moved it, when, and the reports on each move. Above the commits, Find a mark searches marks by name (a mark's exact name opens its moves), the owner groups narrow the page to one group's marks (writers for marks with no group), Moved lately names the marks that moved most recently and where they are, and All marks lists every mark with where it is, the message of the commit it points at and when it moved. Each report's name shows beside its commit, its headline on hover. A commit's page lets you move a mark there with Move here, or roll one back to it.

API#

RequestWhat
GET /api/:owner/:name/marksEvery mark, with how far behind main it is
POST /api/:owner/:name/marksCreate one (name, commit, owner_group, followers, allow_group_rollback, paths)
GET, PATCH, DELETE /api/:owner/:name/marks/:markShow, change, delete
POST /api/:owner/:name/marks/:mark/move, …/rollback{"commit", "note"}
GET /api/:owner/:name/marks/:mark/movesThe moves, newest first, with their reports
GET /api/:owner/:name/marks/:mark/follow?after=ID&timeout=SWaits up to 55 seconds for a move newer than after; returns the newest move, and for the mark's followers its grant and the variables above. With changes=true (and since=COMMIT, the last change handled) it also answers with a change when main's head changed the mark's paths
POST /api/:owner/:name/marks/followThe same for many marks: {"match" or "marks", "cursors": {mark: {"after", "since"}}, "skip", "changes", "timeout"}; returns events (one per mark with something new) and starting cursors for marks it had none for
POST /api/:owner/:name/marks/:mark/pause, …/resumeStop or restart change events ({"note"} on pause)
POST, GET /api/:owner/:name/commits/:commit/reportsFile or read reports

Every move also sends the mark.moved webhook event, with mark, move_id, move_kind and from_commit. The MCP server can list marks and read their moves.

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