List CI checks for a PR's head commit

object

`GET /api/repos/{owner}/{repo}/pulls/{number}/checks`.

annotation_counts

AnnotationCounts

object

Per-level counts for one run's (or a PR's aggregate) annotations — the check-row badge (`3 ✕ / 5 ⚠`). Thin wire mirror of the core `AnnotationCounts` (core stays free of serde/utoipa derives).

failurerequired

integerint64

noticerequired

integerint64

warningrequired

integerint64

blocked_by

array

Human-readable reasons the merge is blocked (empty when mergeable or ungated). Deliberately open vocabulary — render verbatim.

items

string

can_bypass

boolean

Viewer-scoped: this account could merge despite `blocked_by`. `true` only when a bypass would actually DO something — the PR is open, the branch is protected, the PR is not mergeable, the rule sets `enforce_admins: false`, and the viewer holds repo Admin. In particular it stays `false` on an already-mergeable PR, so the UI never offers a "merge without waiting for requirements" button when there is nothing to wait for.

can_enqueue

boolean

checksrequired

array

One check per `context`, newest run first. Several runs can report the same context on one commit (a re-run attempt, a manual dispatch on top of a `pull_request` run); only the newest one's verdict is served, which is the same collapse the merge gate judges.

items

CheckRun

object

One CI check on a PR's head commit: the projection of one job of one workflow run (later also one external commit status).

contextrequired

string

Stable identity of the check: `"<workflow name> / <job key>"`, matrix legs append their values. Branch protection (P2.3) matches required checks against this string.

description

string | null

Human-readable detail (held-for-approval, skipped, …); P2.5 fills per-run test summaries in here.

job_id

string | null

The job row this check projects from (UUID). Absent only on the aggregate check of a job split into matrix legs, which is the whole job rather than one row; every leg's own check carries its row, since the legs share `job_key`.

job_keyrequired

string

quarantined

boolean

`true` when this check is red (`failure`/`error`) but was soft-failed out of the merge gate's `blocked_by` because every one of its failing tests is quarantined (P3.3 of `plans/ci-merge-gating-polish-2026-07.md`). The check still reports its real (red) `state` — this only badges it "quarantined (non-blocking)". Always `false` when merge gating isn't wired, the check is green/pending, or the red isn't quarantine-eligible.

run_idrequired

string

Workflow run the check derives from (UUID).

skipped

boolean

`true` when the job never ran — gated off by its job-level `if:`, or skipped because a `needs:` predecessor did not succeed. The `state` stays `success` (GitHub scores a skipped check as passing, so it must not block a merge on a required check that was never meant to run on this ref); this flag is what lets the UI render "Skipped" rather than a green tick implying work happened.

staterequired

CheckState

superseded

boolean

`true` when the job never finished because the merge queue SUPERSEDED its run: the PR head's run, cancelled once the queue's candidate had `merge_group` runs of the same workflow (ADR 0160). The `state` is `pending`, not `error`: nothing failed, so it must not render red, and the head was not verified, so it is never green — a PR that leaves the queue needs a re-run before it merges directly. Render it as "superseded by the merge queue", not as in flight: it will not resolve on its own.

target_urlrequired

string

App path of the run page (`/{owner}/{repo}/actions/runs/{run_id}`).

checks_summaryrequired

ChecksSummary

object

Roll-up of the check states for the merge box. Counted over the newest-run-per-context set (`neosource_forge::head_checks`), so a run that a re-run superseded is not a second check.

failedrequired

integerint32

`failure` + `error` states — both render red and both block.

pendingrequired

integerint32

skipped

integerint32

Checks whose job never ran (gated off by a job-level `if:`, or a `needs:` predecessor did not succeed). Counted separately from `success`; `success + failed + pending + skipped == total`.

successrequired

integerint32

Checks that ran and passed. Deliberately EXCLUDES skipped ones: a skipped check carries `state: success` so it cannot block a merge, but counting it as "passed" would tell the reader that work happened when it did not — the same claim the per-check `skipped` flag exists to stop the UI making.

superseded

integerint32

Checks the merge queue superseded (`CheckRun::superseded`, ADR 0160): a SUBSET of `pending` (`superseded <= pending`) — they are counted in `pending` too, so a reader that ignores this field still sees the head as not green — never in `failed` (nothing failed). Render `pending - superseded` as in flight and these as superseded.

totalrequired

integerint32

coverage

one of

• CoverageSummary

  object

  Coverage summary for the PR's head-commit run, folded onto `PrChecksResponse.coverage`. Wire mirror of the core `RunCoverageSummary`, with the percentages pre-computed (core stays free of serde/utoipa derives, and the SPA shouldn't hand-roll the divide).

  diff_lines_coveredrequired

  integerint32

  diff_lines_pct

  number | nulldouble

  `diff_lines_covered / diff_lines_total * 100.0` — `None` when `diff_lines_total == 0` (nothing added/changed under coverage, or diff-coverage couldn't be computed for this run).

  diff_lines_totalrequired

  integerint32

  lines_pctrequired

  numberdouble

  `lines_covered / lines_total * 100.0` — `0.0` when `lines_total == 0`.

• null

enforce_admins

boolean

Echoed from the matching branch-protection rule so the client can explain WHY a bypass is or isn't offered. `false` when the target branch is unprotected (or gating isn't wired) — there is then no gate to enforce against anyone.

head_commit

string | null

PR head commit the checks are derived against (40-char Git OID hex, same form as `PullRequestResponse.head_commit`). `null` for a PR whose source branch has no resolved tip yet — `checks` is then always empty.

merge_queue

one of

• PrQueueChecks

  object

  [`PrChecksResponse::merge_queue`]: which commit gates a queued PR, and — when that is the queue's candidate — its checks.

  candidate_commit

  string | null

  The speculative candidate (40-char Git OID hex) that gates the merge — `Some` exactly when `gate` is `speculative` and the entry was frozen on the PR's CURRENT head. Present even while `checks` is empty: a candidate gated only by an external commit status reports no workflow check here, and its statuses are read at this commit.

  checksrequired

  array

  The candidate's workflow-derived checks, the same newest-run-per-context collapse the gate judges and the same row shape as `PrChecksResponse::checks`. Empty when `candidate_commit` is null or nothing has run on it yet; a surface then shows the head's checks.

  itemsCheckRun

  checks_summary

  one of

  • ChecksSummary

  • null

  gaterequired

  MergeQueueGate

  target_branchrequired

  string

  The branch the entry merges into (the candidate is built on its tip).

• null

mergeable

boolean | null

Merge-gate verdict (P2.4): `true`/`false` when merge gating is wired server-side, `null` when it isn't. `false` iff `blocked_by` is non-empty. An unprotected target branch reports `true`.

queue_needed

boolean

up_to_date

boolean | null

Is the head already up to date with the target branch? `Some(false)` = the head is behind the target and can be updated — this is what renders the "Update branch" button. `None` = not knowable (the source branch has no pushed commits, or the target branch has no resolvable tip) or not applicable (the PR is merged or closed: there is nothing to update). Independent of `mergeable`/`blocked_by`: computed whether or not merge gating is wired and whether or not a protection rule matches, because being behind is worth acting on even when nothing gates on it.