Skip to main content

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

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

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:
statusUsed when
queuedThe webhook landed; the runner has not picked up the job.
in_progressThe runner is executing — tests started, evidence streaming.
completedTests done; evidence ingested; coverage computed.
conclusionUsed when
successAll tests in scope passed and no regression vs the base SHA.
failureAt least one test failed, or a previously-confirmed requirement regressed. The PR is blocked if branch protection requires this check.
neutralJob completed but Roboticks was not in scope (no tests touched, no requirements changed) — surfaced as informational, never blocking.
action_requiredA human-in-the-loop step is pending. Most common cause: a PDF requirement upload waiting for review.
cancelledThe PR was closed or a newer commit superseded this run before completion.
skippedThe project policy excluded this run (e.g. draft PR with skip_drafts: true).
timed_outRunner 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. 
## 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.
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.

​
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

Webhooks

The events that drive Check Run creation.

Traceability matrix

The platform UI the Check Run links into.

Change-impact analysis

How we compute “affected requirements” for the summary.

Troubleshooting

Check Run never posts? Start here.