A report is what someone or something says about a commit, under a name (tests, server-prod, review): free text, usually markdown, and optionally a link. Its first line is the headline shown beside the commit on History; the rest (a summary, numbers, the end of a log) is on the commit's page. A body over 64 KiB keeps its start and its end. The next report under the same name on the same commit replaces it.
oak report main --name tests --body "412 passed"
oak report 3f2a8b1c --name tests --body-file report.md # `-` reads stdin
oak report main --name tests --body "412 passed" --url https://ci.example/runs/7
oak report main # the commit's reports
oak report main --name tests # one report, in full
Commits are main, a full hash, or a unique prefix. oak report takes --repo OWNER/NAME (default: the checkout's repository), -r, --remote URL and --json. --move-id ID ties a report to a mark move; oak mark follow files its "deploying", "live" and "failed" reports that way.
Reports are written for the people and agents reading them, so there are no fixed states. Whether a commit passed something is a mark's move: a mark's follower moves the mark when its check passes, and files what went wrong in a report when it fails.
Who can file one#
Anyone who can write the repository files reports, with a key that has the write scope. A mark's followers can also file the report named after the mark on that mark's moves with a read-only key, but never replace a report someone else filed under that name. Everyone who can read the repository reads them.
API#
| Request | What |
|---|---|
POST /api/:owner/:name/commits/:commit/reports | File one: {"name", "body", "url", "move_id"} |
GET /api/:owner/:name/commits/:commit/reports | The commit's reports: commit, and reports with name, headline, body, url, move_id, reporter, updated_at |