# Marks

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

- Everyone who can read the repository can list marks, read their history and wait on their moves, read-only API keys included.
- A mark's **followers** are organization agents listed on it (`--follower NAME`); only the repository's writers and admins see who they are. Only followers get a move's signed grant, and they can file the report named after the mark on its moves with a read-only key (never replacing a report someone else filed). Being a follower doesn't let an agent move the mark; being on its owner group does.
- A mark's owner group moves it forward (agents on the group count). A mark with no owner group can be moved by anyone who can write the repository. An API key needs the `write` scope to move one.
- Whoever may move a mark forward may also pause and resume it (see [Pausing](#pausing-and-rolling-back)).
- Moving a mark back is a rollback. That takes an organization owner or admin, or the owner group too when the mark was created with `--allow-group-rollback`.
- A mark whose grants carry a fixed identity (see [Signed moves](#signed-moves)) is **protected**: moving it is a release step. A person signed in as themselves may (if the rules above let them), and an API key must carry the explicit `release` scope. An organization agent's key can hold it; a person's agent key never may.
- Owners and admins create, change and delete marks, in the repository's **Settings → Marks** or over the API. A change can name the `expected_policy_version` it was made against, and is refused when the mark changed since.

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

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

- **Forward only.** `move` goes to the mark's commit or a later one on `main`'s first-parent history. A commit that isn't on `main` (a branch commit) is refused. Moving to the commit the mark is already at is allowed, which is how you run a deploy again.
- **Rollback.** `rollback` goes to a commit before the mark's.

`--root NAME` makes a mark point into a [root](/docs/roots) 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

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

`oak mark follow` does two jobs, one per script:

- **`--check`** runs on every change. The follower checks `main`'s head out into a work dir (`./oak-mark-<mark>` by default; a clone made the first time) and runs the check there with `OAK_EVENT=change`. When it exits 0, the follower moves the mark to that commit. When it fails, the follower reports "failed (change)" on the commit with the end of the output, and the mark stays where it was. Each change runs once: a fix that lands after a break is the next change, and it goes out on its own.
- **`--run`** deploys every move: the one the check just made, and anyone's move or rollback by hand. It checks the move's commit out and runs the script with the move's signed grant. When the deploy of a move the follower made itself fails, the follower rolls the mark back to the commit it came from (which pauses it, and the rollback is deployed next), or pauses the mark if its credential may not roll back.

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](/docs/api-keys#organization-agents) 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](/docs/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:

| Variable | What |
|---|---|
| `OAK_COMMIT` | `main`'s head |
| `OAK_EVENT` | `change` |
| `OAK_MARK`, `OAK_MARK_PATHS` | The mark, and its paths one per line |
| `OAK_INPUTS` | A hash of what is under the paths |
| `OAK_REPO`, `OAK_REMOTE`, `OAK_LINE` | The repository, the server, and `main` |
| `OAK_REPO_ID` | The repository's numeric id (followers only) |

The deploy runs with:

| Variable | What |
|---|---|
| `OAK_COMMIT` | The commit the mark moved to |
| `OAK_EVENT` | `move` |
| `OAK_MARK`, `OAK_MOVE_ID`, `OAK_MOVE_KIND` | The mark, the move's id, and `create`, `forward` or `rollback` |
| `OAK_REPO`, `OAK_REMOTE` | The repository and server |
| `OAK_LINE` | `main`, or `~NAME` for a mark on a root |
| `OAK_REPO_ID` | The repository's numeric id (followers only) |
| `OAK_GRANT`, `OAK_GRANT_SIGNATURE` | The 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](#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:

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

```bash
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](/docs/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

| Request | What |
|---|---|
| `GET /api/:owner/:name/marks` | Every mark, with how far behind `main` it is |
| `POST /api/:owner/:name/marks` | Create one (`name`, `commit`, `owner_group`, `followers`, `allow_group_rollback`, `paths`) |
| `GET`, `PATCH`, `DELETE /api/:owner/:name/marks/:mark` | Show, change, delete |
| `POST /api/:owner/:name/marks/:mark/move`, `…/rollback` | `{"commit", "note"}` |
| `GET /api/:owner/:name/marks/:mark/moves` | The moves, newest first, with their reports |
| `GET /api/:owner/:name/marks/:mark/follow?after=ID&timeout=S` | Waits 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/follow` | The 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`, `…/resume` | Stop or restart change events (`{"note"}` on pause) |
| `POST`, `GET /api/:owner/:name/commits/:commit/reports` | File or read [reports](/docs/reports) |

Every move also sends the `mark.moved` [webhook](/docs/webhooks) event, with `mark`, `move_id`, `move_kind` and `from_commit`. The [MCP server](/docs/mcp) can list marks and read their moves.
