Get the Action

Docs

Quickstart

Five lines of workflow YAML -- the shape the Action will take when it ships. The Action itself ships at P1; nothing below runs yet.

- uses: Grade-Inc/corund-action@v0
  with:
    checks: c1,c2
    required-path: tests/
    loud-skips: tests/loud_skips.txt

checks lists which of C1-C4 to run; required-path is the directory C3 gate-fold requires changed test files to live inside (see required-path mapping below); loud-skips points at the committed allowlist C2 checks against (see loud-skip allowlist format).

GitHub App install

The GitHub App is registered as corund-app under the Grade-Inc organization. Once it is live, installing it on an org or a chosen set of repos goes through GitHub's own install flow, at this URL pattern:

https://github.com/apps/corund-app/installations/new

Pending the owner's word -- this link is not live yet. The App ships alongside the Action at P1/P2; until then, the Free tier's self-hosted Action above is what actually runs against a pull request.

Check reference

Every check produces one receipt: what ran, on which SHAs, and the verdict. A crashed check reports crashed, never green.

C1

Red-on-revert

Reverts the PR's non-test diff onto base and requires its new tests to fail, then restores the fix and requires them to pass. Both runs land in the receipt, so a passing test suite that was never actually exercised cannot read as proof.

C2

Skip audit

Every silent skip in the suite becomes a CI failure unless it is named on the repo's committed loud-skip allowlist with a reason. Vacuous green -- a suite that exits 0 while quietly not running the thing it claims to run -- has nowhere to hide.

C3

Gate-fold

Every test file touched by the diff must be tracked in git and inside the branch-protection required path, checked out with enough history to mean anything. A test that exists but cannot gate is a report, not a case.

C4

Approval binding

A human approval is bound to the exact commit SHA it was given for. Any new commit -- including a rebase that leaves the diff unchanged -- voids the approval until the gates re-run on the new SHA. Honest line: GitHub branch protection can already dismiss stale approvals natively. C4's addition is binding the approval to the verdict SHA with a receipt, and an org policy that says so.

Receipt anatomy

Every run -- self-hosted Action or App -- produces one receipt, in this shape:

Corund · PR #214 · receipt GATE 
$ corund check --pr 214
base 434550de → head 8f21c7aa

C1 red-on-revert   revert diff, run new tests
                   24 tests RED  ← proof of life
                   restore fix … 24 tests pass
C2 skip-audit      0 silent skips (2 loud, allowlisted)
C3 gate-fold       test files tracked, in required path
C4 approval-sha    word bound to 8f21c7aa (fresh)

VERDICT            PROVEN

Loud-skip allowlist format

One skip site per line in a committed tests/loud_skips.txt, per that file's own header: <path>::<test-or-line>, whitespace, then a reason. <path> is relative to the repo root; <test-or-line> is a test function name (ClassName::test_method for a method on a class) or L<lineno> when there is no enclosing test_* function. C2 fails the build on any skip not named here -- the file is edited only by PR review; the check itself never writes to it.

<path>::<test-or-line>  <reason>
tests/test_ingest.py::test_optional_ocr_path  requires an opt-in local dependency, skipped in CI by design

Required-path mapping

C3 gate-fold checks that every test file touched by a diff is tracked in git and sits inside the same path your branch-protection required status check actually covers. The Action's required-path input (see Quickstart) names that path -- tests/ by default -- and it must match the directory your required check's own test run reads from. A changed test file that lands outside required-path exists in the diff, but does not gate: C3 reports it as a report, not a case, which is the same rule C3 applies to itself.

Self-host guide

The Action runs entirely on your own runners -- GitHub-hosted or self-hosted -- inside your existing workflow. For the Free tier there is no Corund-run service in the path at all: the four checks execute inside your CI job, and the receipt posts as a check run on the pull request the same way any other Action's output does.

Honest cost note: C1 re-runs your suite twice -- once reverted, once restored -- so CI minutes roughly double on gated pull requests. Scope checks: to the PRs that matter (agent-authored, a label, a path filter) if that cost matters to you; see pricing for the same note in dollar terms.

Security

The GitHub App requests the minimum scopes a check run needs, and nothing more. This repository has no app/manifest.json yet, so the list below is derived from SECURITY.md, not from a manifest -- it will be regenerated from the manifest, asserted by a test, the day one exists:

  • checks: write
  • pull_requests: read
  • contents: read
  • metadata: read

Customer code is never retained past run scope: the diff, the reverted tree, and the test output exist only for the duration of the check run that produced the receipt.

Sources

Every stat used anywhere on this site is pinned to a named external report, with the exact sentence it supports. A stat that cannot be pinned to a named report is dropped, not softened. Full list, with report/publisher/date/URL for each: /marketing/sources.md in the repo.