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. People and bots move marks to record what has passed what: server-good for the newest commit the server tests passed on, cli-approved for the release someone signed off, server-prod for what is deployed. We suggest naming them <area>-<state>. A deploy is a mark that a machine follows: when the mark moves, the machine checks out the commit and runs your deploy script.

Oak runs none of your code for this. The tests, the approvals and the deploys run where you run them, and a mark is how they hand a commit to each other.

Who can do what#

Create, move, roll back#

oak mark create server-good
oak mark create server-prod --owner-group deploy --requires server-good
oak mark move server-good main                 # main's head
oak mark move server-prod 3f2a8b1c --note "ship the new pull path"
oak mark rollback server-prod 1d9e0c77         # an earlier commit
oak mark list
oak mark show server-prod
oak mark log server-prod

A mark starts at main's head unless you pass --commit, and not ahead of the marks it requires. 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.

Following a mark#

oak mark follow server-prod --repo acme/web --run scripts/deploy.sh

oak mark follow waits for the mark to move. Run it as one of the mark's followers so its script gets the move's signed grant. Anyone else gets moves without it, and oak mark follow stops with an error unless you pass --no-grant, for a script that only needs OAK_COMMIT, OAK_MARK and the like. For each move it checks the commit out into a work dir (./oak-mark-<mark> by default; a clone of the repository made the first time), runs the script there, and files a report on the commit under the mark's name (--report-name picks another): "deploying (move #12 by zach)", then "live (move #12)" or "failed (move #12)" followed by the end of the script's output. Arguments for the script go after --.

It handles one move at a time. If the mark moves several times while a deploy runs, only the newest move runs next. The last move it handled is kept in a state file (--state-file, default <dir>.follow.json), so a restart carries on from there; a move that was running when the follower stopped is reported failed and not run again (move the mark again to retry). --once handles at most one move and exits, which suits a cron job or a test. --no-checkout runs the script without checking anything out.

The script runs with:

VariableWhat
OAK_COMMITThe commit the mark moved to
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 scripts written before these, and are deprecated.

Secrets stay on the machine that follows: put them in its environment, not in Oak. Following needs only a read-only key; filing the reports needs write access, so a deploy machine usually runs as an organization agent on the mark's owner group.

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 move's follower files reports on the commit, and anyone can file their own with oak report: what the tests said, a deploy's log, a review. Whether a commit passed something is a mark's move: the test runner that passes moves server-good, and the one that fails writes what went wrong in its report.

On the web#

Marks show on the History tab. Each commit names the marks pointing at it: the first two (your own groups' marks first, then the most recently moved), then +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. Find a mark above the commits searches marks by name; typing a mark's exact name opens its moves. Each report's name shows beside its commit, its headline on hover. A commit's page lists the marks you may move with Move here or Roll back here, and says which requirements aren't met yet.

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, requires, required_approvers, followers, allow_group_rollback)
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
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].