# Reports

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.

```bash
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](/docs/marks) 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](/docs/marks#following-a-mark) 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` |
