The CI backstop

Hooks are advisory by construction: --no-verify and hook.skip are each one command away, deliberately, and a teammate whose machine never enrolled runs nothing at all. So the question "what actually stops a bad commit reaching the default branch" has one honest answer, and it is not a hook — it is CI, where nothing can be skipped from a laptop.

greengate does not run in CI — on purpose

The obvious move would be an greengate run step, or a marketplace action. Deliberately not. greengate's job is local ergonomics: one binary orchestrating many tools with scoped selection, index fidelity, live progress, and escape hatches a human sitting at the keyboard is entitled to. CI wants none of that — it wants the real tools, called directly:

  • failures attribute to the tool that found them, in the tool's own words, with the platform's log folding and annotations;
  • each tool gets first-class caching, matrices, and versions pinned by the workflow, not by whatever binary a runner happens to have;
  • there is no second opinion to keep in sync: when cargo clippy disagrees between laptop and CI, that is a toolchain version question, not an greengate question.

The checks that exist only inside greengate — ban-terms, the secrets scan, large-files, merge-conflict, the commit-message and branch-name conventions, pull-rebase — are deliberately not reproduced in CI. They are local ergonomics (catch it before it exists) or they have a better server-side answer (GitHub's own push protection and 100 MB limit, platform merge tooling). Losing them in CI loses nothing the tools below don't already guard: a debugger; that slips past the local hook still has to survive the test suite and review.

One thing this repository points CI at does run there, and it is deliberately not greengate: attest, a single-purpose verifier that reads a signed note and reports which checks it covers. It runs no checks and has no opinions to keep in sync — it verifies a document about work that already happened, which is the opposite of the second-opinion problem above. It lives in its own repository precisely so this rule can stay written as it is; greengate is still not installed on any runner.

The templates

Copy the file for your stack into .github/workflows/ (GitHub) or .forgejo/workflows/ (Forgejo), then prune the steps your repository does not use. Each step is annotated with the greengate check it mirrors, so the local and CI stories stay legible against each other.

Or fetch one directly:

$ curl -fsSL https://raw.githubusercontent.com/greenharness/greengate/main/templates/ci/github/rust.yaml \
    -o .github/workflows/checks.yaml

What maps where

greengate check (local)CI step
pre-commit-cargo-fmtcargo fmt --all -- --check
pre-commit-clippycargo clippy --workspace --all-targets --all-features -- -D warnings
pre-push-cargo-testcargo test --workspace --all-features
pre-push-audit-rustcargo audit
pre-commit-lint-jsnpx --no-install eslint --max-warnings 0 .
pre-push-run-tests-jsnpm run typecheck / test:unit / test --if-present
pre-push-audit-jsnpm audit / pnpm audit, per lockfile directory
pre-commit-ruff / pre-commit-pyrightruff check . / pyright --warnings
pre-push-pytestpytest
pre-push-audit-pythonpip-audit -r requirements.txt
pre-commit-gofmt / pre-commit-go-vettest -z "$(gofmt -l .)" / go vet ./...
pre-push-go-testgo test ./...
pre-push-audit-gogovulncheck ./...
ban-terms, secrets, large-files, merge-conflict, commit/branch conventions, pull-rebasedeliberately local-only — see above

One shape carries over exactly: the audits. Locally they warn on a branch push and block a v* tag push; the templates express the same split natively with continue-on-error: ${{ !startsWith(github.ref, 'refs/tags/v') }} — advisory red on branches, a hard failure when a release is leaving the building. That mirrors what this repository's own release workflow enforces for itself.

Keeping the two in step

The hook is the fast feedback; CI is the same verdict, slower and unskippable. When they disagree, it is almost always a tool version — pin the versions your workflow installs, and consider a tool pin in greengate.conf so the laptop warns when it drifts from what CI runs.

Skipping what pre-push already proved

"CI is the backstop" does not require CI to repeat work it can verify happened. When pre-push has just run the suite against the pushed tree and every block gate passed, re-running the identical suite on the identical tree buys a second copy of the same answer — real money on a resource-constrained runner fleet. So greengate can leave a receipt:

ssh-keygen -t ed25519 -N "" -f ~/.ssh/greengate-attest   # once, per machine
git config greengate.attest true                          # per repository

With the toggle on, a push whose pre-push block gates all passed writes a note on each pushed tip in refs/notes/greensummit and pushes that ref alongside the branch. The note is a four-line payload plus an SSH signature over exactly those bytes:

greensummit-v2
tree <the tree the gates ran against>
gates pre-push-cargo-test pre-push-audit-rust
platform aarch64-macos
amont 1.9.0

-----BEGIN SSH SIGNATURE-----
…
-----END SSH SIGNATURE-----

This does not repeal "greengate does not run in CI". CI still never executes greengate — the templates' attest step is greenharness/greensummit, which needs nothing but git and ssh-keygen, and skips a test step only when all four hold:

  1. the signature verifies against .forgejo/allowed_signers (or your platform's path), a file committed in the repository, whose entry is pinned to the greensummit namespace:

    you@example.com namespaces="greensummit" ssh-ed25519 AAAA…
    
  2. the attested tree is byte-for-byte the tree CI checked out — not the commit hash: a reword keeps its attestation, a single changed byte loses it, and a PR merge commit whose tree drifted from the tested tip never skips;

  3. the step's own gate is named in gates. The list holds only checks that PASSED — Warned and Unavailable never appear, because "could not run" is not "passed" — so a CI step with no local mirror (an e2e suite, an image build) is never skippable by construction;

  4. the attestation's platform is the platform asking. A pass is a pass on something.

A matrix asks the fourth question for you

cargo test green on an arm64 Mac is no evidence at all about the Windows leg of a matrix — and a mechanism that let one laptop retire three platforms' CI would be the unsound version of this whole idea. So the note records where the suite ran, and greengate attest covered defaults to requiring that platform to equal the verifier's own:

legattestation saysoutcome
macos-latestplatform aarch64-macosskips — that suite really ran here
ubuntu-latestplatform aarch64-macosruns
windows-latestplatform aarch64-macosruns

No per-leg configuration: every leg runs the same one-liner and only the matching one finds anything covering it. greengate's own CI is the worked example — a laptop push retires the macOS leg's cargo test and leaves the other two exactly as they were.

For a suite whose result genuinely does not depend on where it ran — a pure-JS unit run, most pytest suites — the workflow says so, once, in a line that is committed and reviewed like any other:

- id: attest
  uses: greenharness/greensummit@v2
  with:
    platform: any

That is a claim about the suite, so make it where the suite is defined rather than on the signing side: the machine holding the key should not get to decide that its results travel.

Reading the result

The action publishes two outputs. Use gates:

- run: cargo test --workspace
  if: ${{ !contains(fromJSON(steps.attest.outputs.gates), 'pre-push-cargo-test') }}

gates is a JSON array, and contains over an array matches elements. The other output, covered, is the same names as a string, where contains matches substrings — so a gate named pre-push-cargo-test-slow satisfies a check for pre-push-cargo-test and skips the real suite. covered is kept only for workflows written against the older inline templates; new ones should not use it.

Everything is fail-open, and the action says why it found nothing rather than leaving you guessing:

greensummit: attested on aarch64-macos, this leg is x86_64-linux
greensummit: no attestation found for tree 9f2a1c…

If you would rather not depend on an action, greensummit covered (cargo install greensummit) is the same verifier as a binary, and greengate attest covered runs it too, through the greensummit library greengate links (decisions ADR-0037), for CI that is neither GitHub nor Forgejo. All of them answer to the format in SPEC.md.

Origin is the source of truth. greengate attest covered treats the local refs/notes/greensummit as a mirror of origin's: deleting that ref on origin revokes every attestation it held — the next covered in any clone deletes its copy and prints how to undo that — and an origin that cannot be reached covers nothing, with the reason on stderr. The spec in .github/greensummit-inputs may mark a path with a leading ? (?build.rs): it may be absent, and the gate re-runs the day it appears.

What signs is the machine that ran the tests, so the trust statement is exactly "whoever holds greengate.attestKey vouches for this tree" — the same trust you extend by pushing at all when you are the only committer. On a team, that key is a shared authority: hand one to each developer (one allowed_signers line each) or accept that any holder can mint "tests passed". And the failure doctrine is the gate stamps' own, one direction only: no note, an unknown format version, a foreign or tampered note, a mismatched tree, a signer CI never heard of — every one of them reads as "no attestation", and no attestation means CI runs the tests. The mechanism can only ever save a redundant run; it cannot skip a check that did not happen. --no-verify skips pre-push entirely, mints nothing, and CI quietly does the full job — which is the backstop doing exactly what it is for.

A gate the busy host deferred

Under set onBusy defer (ADR-0013), a heavy gate whose host slot did not free in time is deferred: it does not run locally and is never attested, so the attest step leaves it out of gates and the CI step runs it, exactly as for a gate that was never run. Nothing in CI changes. What a repository owes is the promise behind the line: every heavy gate it may defer has a CI step.

Reusing a result when only plans changed: declared inputs

Every cache above is keyed by the whole tree, so a commit that changes only docs/plans/*.md — the plan that opens a branch and the closing commit that records its verification — misses all of them. .github/greensummit-inputs lets a repository say what each gate reads; a result is then reused on any tree whose declared paths are byte-identical to the ones it passed on (attest's input fingerprints). Both halves use the same fingerprint, from one module (crates/greengate-runtime/src/attest_inputs.rs):

  • CI verifies the signature as before, but on the fingerprint.
  • The local hooks file each gate's stamp under its fingerprint too, in refs/notes/greengate-gate-inputs, and honour it at pre-commit (judged on the staged tree, so partial staging is judged on what is committed) and pre-push. Never run git notes prune on that ref: its keys are not objects. A gate the spec does not declare keeps the whole-tree behaviour, and so does every gate when the spec is missing, invalid or ambiguous. The token's identity (command, tool, greengate version) still has to match.

The grammar cannot exclude paths, so a declaration is only as good as its completeness: a gate that omits something it reads is skipped wrongly the day that something changes. greengate attest check-inputs --require <gate>… (run by make check, gates listed in the Makefile's ATTEST_GATES) fails unless each named gate declares every tracked file, by real ancestry: crates/foo never stands for crates, and one gate is never rescued by another. Only docs/plans/ is exempt, and the spec itself, .gitattributes and .gitmodules are always part of a fingerprint. Exit 0 covered, 1 something is not covered, 2 no usable spec; it is the opposite of covered, which fails open. A new top-level path or docs/ child therefore fails the check until it is declared for every gate — a deliberate cost of a skip nobody has to trust.

With no declaration: the canonical tree

A repository that declares nothing needs nothing: since amont 1.56.0 the same reuse works with no greensummit-inputs file, on attest 1.5.0's canonical tree. The canonical fingerprint is that of the tree with the content of the top-level docs/plans/ left out and its existence kept, so a closing plan commit reuses every gate while a plan added, deleted or renamed, or any other path changed, does not. Nothing is declared, so nothing can be under-declared and no completeness check is needed.

  • The push adds canon <fp> to the signed block and files the block under the canonical key in refs/notes/greensummit-inputs (a repository with a valid spec keeps its input lines and gains the canon line).
  • The local hooks file each gate's stamp under the canonical fingerprint too, in refs/notes/greengate-gate-inputs, and honour it at pre-commit and pre-push. A repository with a spec that is valid keeps its declared route; one whose spec is invalid, ambiguous or unlistable gets neither route, and the gate runs.
  • The cost of the exemption: a gate that reads the contents of a plan (a formatter or linter over the whole tree, a link checker) would be skipped on a plans-only change. Ignore docs/plans in that tool's configuration, or opt the repository out with set planExempt off in greengate.conf (see configuration).

In CI: verify, run what is uncovered, sign what passed

ci.yaml splits the work in three so that no job that runs the test suite holds the key:

  1. verify always runs make attest-inputs (an undeclared new file changes no fingerprint, so only this catches it), then asks attest's verifier once per platform which gates a signature covers, and prints one plain line per gate: <gate>: skipped, a signature covers this tree's declared inputs (ADR-0024) or <gate>: running, no valid signature. It names no commit: a signed payload identifies a tree. A schedule run covers nothing.
  2. The heavy jobs (rust, msrv, deps, the test legs, the Windows cargo test step) run only when uncovered. test takes its matrix from verify, because a job-level if cannot see the matrix. The Windows installer and end-to-end steps always run: they install the latest published release, an external input no fingerprint captures. A job that passed writes a result file (gate, platform, tree) and uploads it. The load scenarios (make test-load) are the load job, gates ci-load-ubuntu and ci-load-macos.
  3. sign is the only job with the key. It signs a result only when it succeeded, names the tree sign itself is standing on, and names the platform the workflow declares for that gate (scripts/ci-attest-sign-plan.sh), one block per platform. It runs on push and on same-repository pull requests, never for a fork (no secret) and never on schedule. A branch push runs through pull_request, so that is where a branch's signatures are made; the merge to main finds them again because the declared inputs are unchanged.

Which event proves what

A tree is tested once per platform, at the cheapest point that still stops a bad release (decisions plan 2026-10-17-amont-ci-proves-platforms-once):

eventruns
pull requestLinux: rust, msrv, deps, hooks (ubuntu)
push to mainwhat the pull request deferred: hooks (macos), the Windows cargo test, both load legs, each skipped where a signature covers the tree
tagnothing new: the release waits until every gate is attested for the tagged tree

A pull request runs macOS, Windows and load too when it changes something platform-specific (scripts/ci-platform-touched.sh). That means the workflows, the CI scripts, the toolchain or dependency tree, the installers, npm/, templates/, or a product source file with a platform cfg. Adding the full-ci label also runs everything. A deferred gate says so in the attestations summary: <gate>: deferred to the push to main. A platform can therefore go red on main after a green pull request; that is fixed forward, and no release ships until it is green.

The trust is the trust of write access: the workflow and the scripts sign runs come from the ref under test, so whoever can push a branch can edit them, and allowed_signers, and any job running that code could upload an artifact under any name. The split is separation of duties (a test job holds no key and signs nothing); against a hostile pull request the guarantee is write access. .github/CODEOWNERS states that intent. A signature made with a key added in a pull request covers nothing on main, whose own allowed_signers decides.

A tracked file that configures a gate (greengate.conf) must be a declared input of that gate, or a change to its scope would be invisible to the fingerprint: a gate whose declaration omits a tracked greengate.conf is not offered the fingerprint route at all, and keeps the whole-tree behaviour. Settings outside tracked files are not in any fingerprint; they were not in the whole-tree key either.

Skipping lint: tree gates

Test gates are signed from pre-push. Lint and format are different: the pre-commit linters see staged files only, so their pass says nothing about the whole tree. A tree gate (a tree line in greengate.conf) runs the whole-tree command at commit, beside the other checks, and its pass is attested as tree-<name>:

- id: attest
  uses: greenharness/greensummit@v2
  with:
    anywhere: tree-eslint     # formatting and lint do not depend on the platform

- name: Lint
  if: ${{ !contains(fromJSON(steps.attest.outputs.gates || '[]'), 'tree-eslint') }}
  run: npm run lint

Command parity

An attestation names a gate, and a gate is worth only the command behind it. So the CI step must run exactly the gate's normalized declaration:

  • the declared command;
  • with {cache} removed;
  • then a dangling trailing -- removed;
  • then whitespace collapsed.

tree eslint eslint * attest npm run lint -- {cache} requires run: npm run lint. Tool resolution is part of the command (uvx ruff@0.16.0, uv run, npm run), so CI and the laptop resolve the same tool. One gate proves one command: two CI steps (ruff check and ruff format --check) are two gates.

greengate tree-parity (and the pre-commit-tree-parity check) enforce this. It fails closed on a gated step it cannot read with certainty:

  • a block scalar, an anchor or alias, a quoted form with escapes, or ${{ }} in run:;
  • a step-level env: or shell:, or a working-directory: the gate does not declare as cwd=;
  • any env: or defaults: the job or workflow hands down.

The one inherited setting it accepts is defaults: run: shell: bash, and only for a simple command: no pipe, list, redirection or substitution. There, bash's -e and pipefail cannot change the verdict. Run greengate tree-parity as an ungated CI step, so a drift committed with --no-verify still fails.

A step skipped on a built-in test gate (!contains(…, 'pre-push-cargo-test'), and likewise pre-push-go-test, pre-push-pytest, pre-push-run-tests-js) is compared with that gate's local command, and a difference is a warning, never a failure: CI is skipping a step on a signature of a different command. The equivalences it accepts:

  • cargo test, with --workspace and --all-features optional;
  • go test ./...;
  • pytest, python -m pytest, or uv run [--no-sync|--frozen] pytest;
  • one of typecheck, test:unit or test, through npm, pnpm or yarn.

-q and -v are ignored. Anything else differs: a coverage floor, -race, --locked, a package subset, a make target, a pipe. A check only CI makes belongs in a step that is never skipped.

The provenance record (not a skip)

Next to its attestation, a push can publish a second signed note, refs/notes/greengate-provenance: what the push carried besides its tests, the plan it implements and the verdicts given on it (decisions ADR-0036). amont-agent writes the unsigned payload when its implementation-review hook passes a push with a plan; greengate's pre-push signs it with the attestation key under the namespace greengate-provenance and publishes it by tree and by commit, with the same append-and-push loop as attestations. The format is the attest SPEC's greengate-provenance-v1 section.

CI never reads it, and no step is skipped on it. amont-agent shipped <plan> does: it lists each pull request a plan shipped in, its merge commit, its release, and the record that went out. A repository's allowed_signers must list the namespace (namespaces="greensummit,greengate-provenance,amont-provenance") for a record to verify.