> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Check Runs
> What the Roboticks GitHub Check Run shows on every PR — coverage delta, requirement deltas, regressions, and drill-in links.
# Check Runs
A Check Run is the surface where Roboticks meets the PR author. It's the single line on the PR that says *"50 of 51 requirements still confirmed; 1 regression in REQ-014"* and links into the platform for the full story.
## Lifecycle
```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
stateDiagram-v2
[*] --> queued: PR opened / synced
queued --> in_progress: Runner picks up job
in_progress --> completed: JUnit + MCAP ingested
completed --> [*]
```
Each transition is a separate `POST /repos/{owner}/{repo}/check-runs` (or PATCH) and shows up on the PR almost immediately. Typical timing on a hosted runner: `queued → in_progress` in \~10 s, `in_progress → completed` for a small repo in 30–90 s.
## Statuses and conclusions
GitHub's Check Run API splits `status` (the lifecycle) from `conclusion` (the outcome). Roboticks uses them as follows:
| `status` | Used when |
| ------------- | ------------------------------------------------------------ |
| `queued` | The webhook landed; the runner has not picked up the job. |
| `in_progress` | The runner is executing — tests started, evidence streaming. |
| `completed` | Tests done; evidence ingested; coverage computed. |
| `conclusion` | Used when |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `success` | All tests in scope passed and no regression vs the base SHA. |
| `failure` | At least one test failed, **or** a previously-confirmed requirement regressed. The PR is blocked if branch protection requires this check. |
| `neutral` | Job completed but Roboticks was not in scope (no tests touched, no requirements changed) — surfaced as informational, never blocking. |
| `action_required` | A human-in-the-loop step is pending. Most common cause: a PDF requirement upload waiting for review. |
| `cancelled` | The PR was closed or a newer commit superseded this run before completion. |
| `skipped` | The project policy excluded this run (e.g. draft PR with `skip_drafts: true`). |
| `timed_out` | Runner exceeded the project's max wall-clock budget. |
`success` and `failure` are the load-bearing ones; the others exist to communicate edge cases honestly instead of forcing them into a green check.
## Summary markdown
The body of the Check Run is rendered markdown. The shape is consistent across all PRs so reviewers learn to scan it quickly.
```markdown theme={null}
## Roboticks
**Result:** ✅ 50/51 requirements confirmed, 1 regression
**Tests:** 142 ran · 141 passed · 1 failed · 0 skipped
**Coverage delta vs `main`:** −1 confirmed, +0 gaps, +1 regression
### Affected requirements
| Req | Title | Before | After | Test |
|---|---|---|---|---|
| REQ-014 | E-stop releases brake after reset | ✅ confirmed | 🔴 regression | `tests/test_estop.py::test_brake_release` |
| REQ-027 | Battery low triggers RTH | ⚪ unconfirmed | ✅ confirmed | `tests/test_battery.py::test_rth_trigger` |
### Files driving the change
- `src/safety/estop.cpp` — 14 lines changed, touches 3 confirming tests
- `src/safety/brake.cpp` — 6 lines changed, touches 1 confirming test
[Open the full traceability view →](https://app.roboticks.io/p/warehouse-amr/traceability?pr=142)
[Download evidence pack (draft) →](https://app.roboticks.io/p/warehouse-amr/evidence/draft/abcd123)
```
A few choices worth flagging:
* **Coverage delta is reported against the base SHA**, not against the latest commit on `main` — so a long-lived branch isn't penalised for drift it didn't cause.
* **Regressions are called out separately** from new failures. A regression means *"this requirement used to be confirmed and now isn't"*, which is a stronger signal than *"a test failed somewhere"*.
* **Every cell is a deep link**, not a free-text reference. Reviewers click straight into the matrix.
## Annotations
For each failing test we attach a GitHub annotation to the file and line that triggered the failure. The annotation contains:
* The failure message (truncated to 64 KB per GitHub's limit).
* The requirement(s) the test confirms, so the reviewer sees the blast radius without leaving the diff view.
* A link back to the platform run page.
```text theme={null}
tests/test_estop.py:42 failure
test_brake_release: expected brake state RELEASED within 100ms, got HELD after 215ms
Confirms: REQ-014 (E-stop releases brake after reset)
Run: https://app.roboticks.io/p/warehouse-amr/runs/r_8f3a
```
Annotations are scoped to changed files by default; you can opt into "annotate all failures, even untouched files" in **Settings → Project → Check Run policy**.
## Conclusion ↔ branch protection
To make a Roboticks run **required** for merge:
1. In GitHub: **Repository → Settings → Branches → Branch protection rules → Edit `main`**.
2. Under **Require status checks to pass before merging**, add `Roboticks`.
3. Tick **Require branches to be up to date before merging** if you want stale-branch protection.
The check name `Roboticks` is stable across runs — no version suffix, no per-job qualifier — so a single branch protection rule covers all future PRs.
For air-gapped GHES customers, the check name is configurable per installation. See [Self-hosted runners](/runners/installation).
## Re-running
Two re-run paths, both supported:
* **GitHub Re-run** — the user clicks **Re-run all jobs** on the Check Suite. GitHub sends a `check_suite.rerequested` event; we dispatch the same job spec to the same SHA.
* **Roboticks Re-run** — from the run page in the dashboard. Useful when a previous run was poisoned by a transient runner issue rather than a code problem; this path can also pin a specific runner pool.
Re-runs do **not** alter the prior Check Run; they create a new one. The Check Suite shows the most recent.
## What the PR comment adds
The Check Run is the canonical surface; the optional PR comment is a courtesy. It's identical to the Check Run summary, but pinned at the bottom of the PR so reviewers can read it without leaving the Conversation tab. Disable it project-wide under **Settings → Project → Check Run policy → Post PR comment: off**.
## Next
The events that drive Check Run creation.
The platform UI the Check Run links into.
How we compute "affected requirements" for the summary.
Check Run never posts? Start here.