Gate Releases on GitHub Check Runs, Not Commit Status
GitHub Actions reports results as check runs, not statuses. Build a Node.js release gate that waits for required checks on an exact commit SHA before tagging.
A release script usually has one job before it does anything permanent: confirm that CI passed on the exact commit you are about to tag. It sounds like a single API call. On GitHub it is actually two different systems, and if you ask the wrong one, your gate either waits forever or waves through a commit nobody tested.
This tutorial walks through why the combined status endpoint is the wrong question for GitHub Actions, how the check runs API answers the right one, and how to build a small Node.js gate script you can drop into a release workflow or run from your terminal.
Two ways GitHub records "CI passed"
GitHub has two parallel mechanisms for attaching pass/fail results to a commit:
- **Commit statuses** are the older model. An integration POSTs a `state` (`error`, `failure`, `pending`, or `success`) with a `context` string such as `ci/jenkins`. You read them back with the commit statuses API.
- **Check runs** are the newer model, part of the Checks API. Each check run has a `name`, a `status` (`queued`, `in_progress`, `completed`, plus a few Actions-only states like `waiting`), and once completed, a `conclusion` such as `success`, `failure`, `cancelled`, `skipped`, `neutral`, or `timed_out`.
GitHub Actions reports every job as a **check run**. It does not create commit statuses. That one detail is the root of the bug.
Why the combined status endpoint lies to you
The tempting endpoint is:
GET /repos/{owner}/{repo}/commits/{ref}/status
It returns a single rolled-up `state`, which looks perfect for a gate. But according to GitHub's docs, that state is:
- `failure` if any context reports `error` or `failure`
- `pending` if there are **no statuses** or a context is pending
- `success` if the latest status for every context is `success`
On a repository whose CI runs entirely on GitHub Actions, there are no commit statuses at all. So the combined state is `pending`, permanently, no matter how green your Actions run is. A script that polls until `success` will time out. A script that someone "fixed" by treating `pending` with `total_count: 0` as acceptable is worse: it now passes on every commit, including ones whose tests failed.
The PR page doesn't help you notice, because the checks list in the UI merges both systems. Everything looks green there while the API you picked sees nothing.
Asking the right question: check runs for a commit
The endpoint you want is:
GET /repos/{owner}/{repo}/commits/{ref}/check-runs
You can inspect it quickly with the GitHub CLI before writing any code:
gh api "repos/OWNER/REPO/commits/$(git rev-parse HEAD)/check-runs?per_page=100" \
--jq '.check_runs[] | {name, status, conclusion}'
A few query parameters matter for a gate:
- `filter` defaults to `latest`, which returns the most recent run for each check. That's what you want: if a flaky job was re-run and passed, you should judge the re-run, not the original failure. Use `filter=all` only for auditing.
- `per_page` defaults to 30 and maxes out at 100. A monorepo with a matrix build can exceed 30 checks quickly, so always paginate.
- `check_name` narrows the result to one check if you only care about a single job.
- `ref` can be a SHA, a branch, or a tag. For a release gate, **always use the full commit SHA.** A branch name is a moving target. If someone merges between your check and your tag, you validated one commit and released another.
The response is `{ "total_count": N, "check_runs": [ ... ] }`. Each run carries `name`, `status`, `conclusion`, `head_sha`, `started_at`, `completed_at`, and `html_url`.
Decide what "green" means before you write code
The API tells you what ran. It does not tell you what was *supposed* to run. If your gate simply checks "every check run that exists is successful," it will pass when a workflow never triggered at all, for example because a path filter skipped it or a YAML error kept the workflow from loading. Zero failures out of zero runs is not a green build.
So the gate needs an explicit list of required check names, matching the names shown in the PR checks list. Those are the job names (or the job `name:` field), and matrix jobs get suffixes like `test (20)` and `test (22)`.
Then decide how to treat each state:
| Situation | Gate result | | --- | --- | | Required check missing | Wait, then fail on timeout | | `status` not `completed` | Wait, then fail on timeout | | `conclusion` is `success` | Pass | | Any other conclusion | Fail immediately |
I treat `skipped` and `neutral` as failures for required checks. If a job you declared required was skipped, the gate should make a human look at it rather than quietly accept it. Loosen that only if you have a specific reason.
The gate script
Here is a dependency-free Node.js script (Node 18 or newer, since it uses the built-in `fetch`). Save it as `scripts/release/require-ci-green.mjs`.
#!/usr/bin/env node
// Usage:
// GITHUB_TOKEN=... node require-ci-green.mjs owner/repo <full-sha> "lint" "test" "build"
const [, , repo, sha, ...required] = process.argv;
const token = process.env.GITHUB_TOKEN;
if (!repo || !sha || required.length === 0 || !token) {
console.error(
'usage: GITHUB_TOKEN=... node require-ci-green.mjs owner/repo <sha> "<check>" [...]'
);
process.exit(2);
}
if (!/^[0-9a-f]{40}$/.test(sha)) {
console.error(`Refusing to gate on "${sha}": pass a full 40-character commit SHA.`);
process.exit(2);
}
const TIMEOUT_MS = Number(process.env.CI_GATE_TIMEOUT_MS ?? 20 * 60_000);
const INTERVAL_MS = Number(process.env.CI_GATE_INTERVAL_MS ?? 30_000);
async function listCheckRuns() {
const runs = [];
for (let page = 1; ; page++) {
const url =
`https://api.github.com/repos/${repo}/commits/${sha}/check-runs` +
`?filter=latest&per_page=100&page=${page}`;
const res = await fetch(url, {
headers: {
Accept: 'application/vnd.github+json',
Authorization: `Bearer ${token}`,
'X-GitHub-Api-Version': '2022-11-28',
},
});
if (!res.ok) {
throw new Error(`GitHub API ${res.status}: ${await res.text()}`);
}
const body = await res.json();
runs.push(...body.check_runs);
if (body.check_runs.length === 0 || runs.length >= body.total_count) {
return runs;
}
}
}
function evaluate(runs) {
const result = { passed: [], pending: [], failed: [], missing: [] };
for (const name of required) {
const matches = runs
.filter((run) => run.name === name)
.sort((a, b) => new Date(b.started_at ?? 0) - new Date(a.started_at ?? 0));
if (matches.length === 0) {
result.missing.push(name);
continue;
}
const run = matches[0];
if (run.status !== 'completed') {
result.pending.push(`${name} (${run.status})`);
} else if (run.conclusion === 'success') {
result.passed.push(name);
} else {
result.failed.push(`${name} (${run.conclusion}) ${run.html_url}`);
}
}
return result;
}
const deadline = Date.now() + TIMEOUT_MS;
while (true) {
const r = evaluate(await listCheckRuns());
if (r.failed.length > 0) {
console.error(`CI gate failed on ${sha}:\n ${r.failed.join('\n ')}`);
process.exit(1);
}
if (r.pending.length === 0 && r.missing.length === 0) {
console.log(`CI gate passed: ${r.passed.length} required checks green on ${sha}`);
process.exit(0);
}
const waiting = [...r.pending, ...r.missing.map((n) => `${n} (not reported)`)];
if (Date.now() > deadline) {
console.error(`CI gate timed out on ${sha}. Still waiting on:\n ${waiting.join('\n ')}`);
process.exit(1);
}
console.log(`Waiting on: ${waiting.join(', ')}`);
await new Promise((resolve) => setTimeout(resolve, INTERVAL_MS));
}
A few choices are worth calling out:
- **Full SHA only.** The regex check is deliberate friction. It is much harder to accidentally gate on `main` and release whatever `main` points to a minute later.
- **Fail fast, wait slow.** A failure ends the gate immediately, so you aren't stuck polling a build you already know is red. Pending and missing checks get the full timeout, because a queued runner is normal.
- **Defensive sort.** `filter=latest` should already return one run per check name, but the same name can come from two different apps. Sorting by `started_at` keeps the result deterministic, and queued runs with a null `started_at` sort last.
- **Links in failures.** Printing `html_url` turns a failed release into one click to the log.
Run it locally against your current commit:
GITHUB_TOKEN="$(gh auth token)" node scripts/release/require-ci-green.mjs \
OWNER/REPO "$(git rev-parse HEAD)" "lint" "test" "build"
Wiring it into a release workflow
In GitHub Actions, the built-in `GITHUB_TOKEN` can read check runs if the workflow grants `checks: read`:
name: Release
on:
workflow_dispatch:
permissions:
contents: write
checks: read
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Require CI green on this exact commit
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: >
node scripts/release/require-ci-green.mjs
"$GITHUB_REPOSITORY" "$GITHUB_SHA"
"lint" "test" "build"
- name: Tag and publish
run: echo "release steps go here"
There is one trap here that bites almost everyone once: **the job running the gate is itself a check run on the same commit**, and it stays `in_progress` while the gate polls. If your gate checked "all check runs," it would wait on itself until it timed out. An explicit list of required names avoids that by design. Just never put the release job's own name in the list.
If you use release-it or a similar tool, call the script from a `before:init` hook so the gate runs before any version bump, changelog write, or tag is created. A gate that runs after the tag is pushed is only a report.
Edge cases worth knowing
- **Third-party CI that still uses statuses.** Some services report through commit statuses rather than check runs. If you depend on one, read both endpoints and require each named context or check to pass. Don't drop the status API entirely without checking where your signals come from.
- **Very busy refs.** GitHub limits this endpoint to check runs from the 1,000 most recent check suites on a ref. For a release commit that never matters, but it's why the docs point heavy users to listing check suites first.
- **Forks.** The Checks API only tracks pushes in the repository where the suite was created, so a gate on a fork's branch can come back empty. Release gates should run against the upstream repository's commits.
- **Token scope locally.** Any token that can read the repository can list its check runs; a classic token needs the `repo` scope for a private repository. `gh auth token` works if your CLI login can already see the repo.
Takeaways
- GitHub Actions reports results as **check runs**, not commit statuses. The combined status endpoint returns `pending` when no statuses exist, so it can't gate an Actions-only repo.
- Use `GET /repos/{owner}/{repo}/commits/{sha}/check-runs` with `filter=latest`, `per_page=100`, and pagination.
- Gate on an **explicit list of required check names**, pinned to a **full commit SHA**. A missing check is not a passing check.
- Fail immediately on a bad conclusion, wait with a timeout on anything pending, and keep the release job's own name out of the list.
That's about a hundred lines of code, and it closes a gap that otherwise only shows up on the day a broken commit gets tagged.