Reports

Free text about a commit, filed under a name: test results, a deploy's log, a review.

Markdown

All pages

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#

RequestWhat
POST /api/:owner/:name/commits/:commit/reportsFile one: {"name", "body", "url", "move_id"}
GET /api/:owner/:name/commits/:commit/reportsThe commit's reports: commit, and reports with name, headline, body, url, move_id, reporter, updated_at

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