Skip to main content

​
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: 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.
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.
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.