feat: GitHub Action for automated offline DSSE receipt verification in CI

[mahirhir]

Summary

We have an example CI workflow in examples/ci/receipt-check.yml that executes gx receipt verify --offline. Packaging this into a reusable composite GitHub Action (TraceFold/action-receipt-verify) will make it trivial for agent harnesses and developer teams to gate PRs on verified execution receipts.

Acceptance Criteria

• A composite GitHub Action in a dedicated repo or .github/actions/receipt-verify that installs the gx binary.
• Accepts input arguments for receipt file path, public key path, and optional tile checkpoint.
• Fails the workflow (exit code 7) if the receipt does not verify or fails policy admission.

Good first issue for anyone familiar with GitHub Actions composite syntax.

[mahirhir]

Status as of 2026-09-01, with an honest defect note. The repo root now carries a composite action.yml, but as shipped it is a fail-open stub: when the gx binary is absent it prints "Tracefold gate validation passed (stub check)" and exits 0. That is the opposite of the fail-closed behaviour this project claims as its core property, so the acceptance criteria here (install the binary, non-zero exit on verification failure) are not met and the stub must not be used as a real gate yet.

Keeping this open. The proper fix is blocked on pre-built binaries (#7); until then the stub should at minimum fail, not pass, when gx is missing.

[mahirhir]

The minimum fix from the previous comment is done in the development tree and will land here on the next push. What changed, precisely:

• gx absent: the step now prints ::error::gx binary not found -- this check cannot pass without it and exits 1. The "passed (stub check)" line is retired (kept only as a comment in the file for the record).
• gx present: invocation unchanged, with one honest-limit comment added: gx verify-receipts is not a shipped subcommand (the CLI ships gx receipt verify, see examples/ci/receipt-check.yml), so even an installed gx fails this step today -- fail-closed in both branches until the inputs are remapped to the real command.

Verified locally by running the extracted step under bash -e -o pipefail in both states: absent → exit 1 with the error line; a recorder standing in for gx → invoked with the same arguments as before, and its exit code (tested 0 and 7) propagates.

This issue stays open: the acceptance criteria (install the binary, exit 7 on verification failure) are still not met and remain blocked on pre-built binaries (#7). This change only removes the false green.

[mahirhir]

Partial progress, and a correction to this issue's own premise.

What landed (0e08013, on main now): action.yml at the repo root was calling gx verify-receipts --dir <d> --policy <p>. That has never been a subcommand of this CLI — gx verify-receipts answers error: unrecognized subcommand, measured against the built binary. So the action could not pass even with gx installed, and the file said so in a comment rather than being fixed. It now calls the surface that ships:

gx policy lint <PATH>
gx receipt verify <FILE> --offline --checkpoint <F> --checkpoint-key <F> --key <F>

which is the same call shape crates/gx-cli/src/demo.rs::verify_offline uses. Receipts are iterated one file at a time out of receipt-dir.

Two inputs were removed rather than left as decoration: enforce-inverses and fail-on-tamper mapped to no flag. gx receipt verify always checks the DSSE signature, the canonical CID, and inclusion against the head it is given; there is no dial that turns half of it off, so an input claiming to be one was a lie. Added fail-on-empty (default true): a gate with nothing to check must not report green.

Acceptance criteria, honestly scored:

• "installs the gx binary" — not met. The action requires gx on PATH and exits 1 with an install pointer when it is absent. Installing inside the action means either building from source (minutes, per examples/ci/receipt-check.yml) or downloading a release asset. v0.1.2-alpha now exists, so the second road is finally open; it was not when this issue was filed.
• "inputs for receipt file path, public key path, and optional tile checkpoint" — met, as receipt-dir, key, checkpoint, plus checkpoint-key (without it the answer says anchor_authenticated: false, so leaving it optional-and-silent would have been a quiet downgrade).
• "Fails the workflow (exit code 7)" — the number in this issue is too broad. 7 is offline verification failure specifically. An unreadable or malformed receipt exits 1 (VALIDATION_ERROR), measured. The step propagates whichever code gx returns rather than flattening both to one, so a caller can tell "this receipt is a forgery" from "this file is not a receipt".
• "dedicated repo or .github/actions/receipt-verify" — not moved; it is still action.yml at the root, referenced as TraceFold/tracefold@<ref>.

How it was checked, and how it was not. Actions on this repository have not started a job since 20 Aug (billing gate), so this has not been observed running green in CI, and the file says so. Instead tools/action_yml_selfcheck.sh lifts the run: body out of the YAML and exercises all five branches against the built gx: empty dir with fail-on-empty=true exits 1, with false exits 0, missing anchor files exit 1, absent gx exits 1, and a real invocation reaches gx's own receipt parser — which is what proves every flag is accepted. The check was itself checked: fed the old gx verify-receipts call it reports unrecognized subcommand and fails, so it is not a green light that is always on.

Leaving this open. What remains is the install step and the relocation, not the command shape.

[mahirhir]

The remap landed and then came back out again, so here is the trail.

0e08013 (3 Sep, 02:06Z) replaced the gx verify-receipts --dir --policy call with gx receipt verify <FILE> --offline --checkpoint --checkpoint-key --key plus gx policy lint, and dropped enforce-inverses and fail-on-tamper because neither mapped to a flag on the shipped CLI. 7abab17 (3 Sep, 10:05Z), a bulk sync from the development tree, then rewrote action.yml (+25/-91) and put the unshippable call back. Nobody edited this issue, but its subject reverted underneath it.

Restored verbatim in 7b30471, and action.yml on main is now byte-identical to the 0e08013 version. The development tree still holds the old copy, so the next sync reverts it again unless that side is updated first. That is the real remaining work here, and it is not a contributor task.

What is still open for anyone who wants it: a receipt fixture plus a workflow that runs this action end to end. Actions on this repository have not started a job since 20 Aug because of a billing gate, so nothing here has been observed green. The evidence behind the current file is the CLI's own --help output and the call shape in crates/gx-cli/src/demo.rs, which is weaker than a run and should be read that way.