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 clippydisagrees 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-fmt | cargo fmt --all -- --check |
pre-commit-clippy | cargo clippy --workspace --all-targets --all-features -- -D warnings |
pre-push-cargo-test | cargo test --workspace --all-features |
pre-push-audit-rust | cargo audit |
pre-commit-lint-js | npx --no-install eslint --max-warnings 0 . |
pre-push-run-tests-js | npm run typecheck / test:unit / test --if-present |
pre-push-audit-js | npm audit / pnpm audit, per lockfile directory |
pre-commit-ruff / pre-commit-pyright | ruff check . / pyright --warnings |
pre-push-pytest | pytest |
pre-push-audit-python | pip-audit -r requirements.txt |
pre-commit-gofmt / pre-commit-go-vet | test -z "$(gofmt -l .)" / go vet ./... |
pre-push-go-test | go test ./... |
pre-push-audit-go | govulncheck ./... |
ban-terms, secrets, large-files, merge-conflict, commit/branch conventions, pull-rebase | deliberately 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:
-
the signature verifies against
.forgejo/allowed_signers(or your platform's path), a file committed in the repository, whose entry is pinned to thegreensummitnamespace:you@example.com namespaces="greensummit" ssh-ed25519 AAAA… -
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;
-
the step's own gate is named in
gates. The list holds only checks that PASSED —WarnedandUnavailablenever 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; -
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:
| leg | attestation says | outcome |
|---|---|---|
macos-latest | platform aarch64-macos | skips — that suite really ran here |
ubuntu-latest | platform aarch64-macos | runs |
windows-latest | platform aarch64-macos | runs |
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 rungit notes pruneon 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 inrefs/notes/greensummit-inputs(a repository with a valid spec keeps itsinputlines and gains thecanonline). - 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/plansin that tool's configuration, or opt the repository out withset planExempt offingreengate.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:
verifyalways runsmake 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. Aschedulerun covers nothing.- The heavy jobs (
rust,msrv,deps, thetestlegs, the Windowscargo teststep) run only when uncovered.testtakes its matrix fromverify, because a job-levelifcannot 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 theloadjob, gatesci-load-ubuntuandci-load-macos. signis the only job with the key. It signs a result only when it succeeded, names the treesignitself 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 onpushand on same-repository pull requests, never for a fork (no secret) and never onschedule. A branch push runs throughpull_request, so that is where a branch's signatures are made; the merge tomainfinds 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):
| event | runs |
|---|---|
| pull request | Linux: rust, msrv, deps, hooks (ubuntu) |
push to main | what the pull request deferred: hooks (macos), the Windows cargo test, both load legs, each skipped where a signature covers the tree |
| tag | nothing 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
${{ }}inrun:; - a step-level
env:orshell:, or aworking-directory:the gate does not declare ascwd=; - any
env:ordefaults: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--workspaceand--all-featuresoptional;go test ./...;pytest,python -m pytest, oruv run [--no-sync|--frozen] pytest;- one of
typecheck,test:unitortest, 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.