Configuration
Everything is git config. There is no config file of ours, no .amontrc,
nothing to keep in sync — the settings live where a git user already looks for
settings, and --local/--global mean what they always mean.
To bypass or disable rather than tune, see opting out.
Naming a check
Every check has an id, <trigger>-<name> — pre-commit-clippy. Three things
name it, and every config surface reads all three the same way:
| key | reaches |
|---|---|
pre-commit-clippy | that one check |
clippy | that check, on either trigger |
pre-commit | every check on that trigger |
Where several keys reach one check, the most specific wins: full id, then short name, then trigger. So you can downgrade a whole trigger and then exempt one check from that downgrade.
Nothing matches by substring. hook.skip e reaches nothing at all, and
skipping lint-js leaves lint-json-yaml alone — a skip can never silently
couple two checks whose names happen to share a prefix.
Where committed policy sits. A trusted greengate.conf can carry
severity, skip, and set lines.
For one key, the ladder is: built-in default < system < global < policy <
local < worktree < command — the team's committed decision beats your global
preferences, and your local config in that repository beats the team. Between
different keys naming the same check, specificity (full id > short name >
trigger) decides regardless of source. Skips union across every source. On a
git too old for --show-scope (< 2.26) this degrades fail-safe to "all git
config beats policy". A set line reaches an allowlist of the keys on this
page — the thresholds, commit style, autoRebase, timeout,
testPushedTree, minVersion, planExempt — and never fix, trusted,
conventions, or the observability opt-outs, which stay per-machine.
hook.skip — do not run it
Multi-valued; add as many as you need.
git config --add hook.skip pre-commit-clippy # that one check
git config --add hook.skip clippy # on either trigger
git config --add hook.skip pre-commit # the whole trigger
git config --unset-all hook.skip # start over
git config --get-all hook.skip # what is set here
A skipped check is announced on every commit. A config line nobody remembers writing cannot go on silently disabling things — that silence is how a repository ends up with a check everyone believes is running.
For one commit only, without touching config:
git -c hook.skip=clippy commit -m "fix: …"
greengate.severity.<key> — run it, but do not block
Takes the same three spellings, and keeps the signal: the check still runs and still reports, it just stops failing the commit.
git config greengate.severity.clippy warn # runs, reports, does not block
git config greengate.severity.pre-commit warn # the whole trigger
git config greengate.severity.clippy block # back to blocking
warn is usually the right first move when adopting a check into an existing
repository: you get the report immediately and pay down the backlog on your own
schedule, rather than choosing between a blocked commit and a hook.skip you
will forget to remove.
greengate.commit.* — what a commit message must look like
Four keys, and greengate setup walks you through all of them:
| key | default | means |
|---|---|---|
greengate.commit.gitmoji | none | where the type's emoji goes |
greengate.commit.subjectMax | 72 | longest the whole subject may be |
greengate.commit.descriptionMax | 50 | longest the part after type: may be |
greengate.commit.bodyWrap | 72 | column the body is hard-wrapped at; 0 never wraps |
These matter more than they look, because commit-msg is the one hook
hook.skip and greengate.severity do not reach, and git exempts it from
--no-verify. Without these keys the only answers to "I do not want a gitmoji
in every subject" were to comply or to uninstall.
The four placements
git config greengate.commit.gitmoji prefix
| stored as | ||
|---|---|---|
none | feat: add a cart | the default — your subject, untouched |
prefix | ✨ feat: add a cart | |
suffix | feat: add a cart ✨ | commitlint and changelog tools still see the type |
replace | ✨ add a cart | the emoji stands in for the type word |
You always write feat: add a cart, and it is always validated as that —
the placement only decides what gets stored. replace costs you interop, and
that is the trade it is: an emoji is not a type any conventional-commit tool
knows how to read.
Two things hold whatever you choose. The limits measure what you wrote, so the emoji never eats your description budget. And running the hook again over its own output — an amend, a rebase reword — changes nothing.
The limits
git config greengate.commit.descriptionMax 68
git config greengate.commit.bodyWrap 0
68 is the useful number if 50 feels tight: it still fits a 72-column subject
with a short type and no scope. bodyWrap 0 leaves the body exactly as
written, which is what keeps a pasted stack trace or a fenced code block
intact.
A value git cannot parse, or one outside 1..=1000, takes the shipped default
and says so on the commit it happened on — because a limit you believe you
raised and did not is the whole failure mode this project refuses to be quiet
about. A pairing that cannot do anything (a description budget the subject
limit can never accommodate) is reported by greengate list, not by the hook:
the commit path says what is in effect, and the config-reading commands say
what makes no sense.
greengate.conventions
$ git config --global greengate.conventions declared
everywhere (the default) or declared. In declared mode the house
rules — commit-message shape, branch patterns, lint/format gates, test
suites, audits, auto-rebase — run only in repositories that commit an
greengate.conf (an empty one declares), while the safety net (merge-conflict,
secrets, large-files, ban-terms) keeps running everywhere. This is what
makes a machine-wide standing grant (greengate enroll, init.templateDir)
safe on a machine that also clones other people's projects. A held-back
stage announces itself in one line; greengate list reports the state, and
--json carries it as "conventions_apply". An unrecognised value falls
back to everywhere, loudly.
greengate.largeFileWarn / greengate.largeFileBlock
$ git config greengate.largeFileWarn 25
$ git config greengate.largeFileBlock 500
The two thresholds of pre-commit-large-files, in
megabytes: a staged file over the first is named (default 10), one over the
second blocks (default 100 — GitHub's own refusal line).
greengate.recordBypasses — whether a dodged gate is tallied
git config greengate.recordBypasses false # default true
When a commit that a commit-time gate declaration covered lands without that
gate having run — git commit --no-verify, a blocked attempt retried with
it, a gate whose tool was missing — post-commit silently appends one line
per dodged script to $(git rev-parse --git-common-dir)/amont-bypasses.
greengate list shows the tally as "unverified commits". The file is local:
never a ref, never pushed, never sent anywhere.
false stops the counting from now on. The switch exists because "my tool
counts my bypasses" can reasonably read as surveillance, and the answer to
that reading should be a documented off-switch rather than an argument —
though the count is also the first place a slow or flaky check becomes
visible as the thing people route around.
greengate.recordDowngrades — whether a warning is tallied
git config greengate.recordDowngrades false # default true
The companion to the switch above, for the other half of the signal. When a
check FAILS but the severity that applies says warn, the hook silently
appends one line to $(git rev-parse --git-common-dir)/amont-downgrades, and
greengate list shows the tally as "problems that did not block".
That file is what makes a trial readable: set
greengate.severity.pre-commit warn, work for a fortnight, then read which checks
your team would actually have fought. See
Trying it before you impose it.
Local on the same terms as the bypass ledger — never a ref, never pushed,
never sent anywhere — and false stops the counting from now on, for the same
reason its sibling has an off-switch.
Nothing is recorded by a rehearsal (greengate run), and nothing by a check that
actually blocked: the first is not a commit, and the second has nothing to
report.
greengate.progress — one check, one block
git config greengate.progress false # default true
On (the default): everything a pre-commit check says — its own lines and its
tools' captured output — is buffered and emitted as ONE contiguous block when
the check finishes, so twenty concurrent checks stop shuffling their failure
output together. Blocks arrive in completion order. And when stderr is a
real terminal, a live region under the blocks shows one line per running
check — spinner, name, elapsed — so a slow cargo test is a ticking clock
instead of a frozen prompt. The region only ever paints on an interactive
terminal; piped or redirected output, TERM=dumb, and CI logs never see a
control code.
Off: raw streaming, exactly as before — every line lands the moment it is written, interleaved across whatever else is running. The honest cost of the default is that a long-running tool's output arrives when the check ends rather than as it happens; this key is the way back if you want to watch a test suite scroll.
greengate land — push, then prove the ref moved
greengate land # push this branch, read the remote back
greengate land --force # a non-fast-forward, leased on the tip it just read
greengate land --json # one JSON document on stdout, everything else on stderr
greengate land --dry-run # say what a land would push; touch nothing
Not a setting, but the place its contract is written down. It pushes the
current branch (never main or master, and never with uncommitted tracked
changes) to the one URL git remote get-url --push names, as an explicit
<sha>:refs/heads/<branch>, with the pre-push hooks running as for any push.
It then reads the same URL back, re-reading up to three times two seconds
apart on a mismatch.
| exit | status | meaning |
|---|---|---|
| 0 | landed | the remote ref equals the pushed sha |
| 1 | refused | a hook, the server, or a precondition said no (including more than one push destination) |
| 2 | usage | wrong invocation (also printed as a status under --json) |
| 3 | unreachable, unverified | the remote could not be read, or the push was accepted and could not be read back |
| 4 | not-observed | accepted, but the expected tip was not observed; remote_after holds what was |
| 128+n | interrupted | killed by signal n; no retry |
4 does not say an update was lost: another writer may have advanced or
replaced the ref after your push. Look at remote_after before pushing again,
and think twice before --force.
The last line on stderr is always a plain-text verdict, at most 80 columns
wide whatever the branch is called; any commands worth running next are
printed in full on the lines before it. --json prints
{branch, remote, push_url, pushed, remote_before, remote_after, retried, status} on stdout and nothing else.
There is exactly one retry: when the pre-push hook rebased or fast-forwarded
HEAD and said push again, the new HEAD descends from the tip that was read,
and the first push failed. The hook only brings a strictly-behind branch up to
date, so the retry lands nothing new; a diverged branch is a refusal.
The push has no deadline of its own, because its hook runs the whole gate.
Without a terminal it runs with the no-prompt environment, which bounds the
network legs only; a custom ssh command, a credential helper or an
established session can still stall, and Ctrl-C ends it (exit 128+signal).
A branch whose upstream is main or master under another name (what
git worktree add -b <b> origin/main sets up) lands under its own name: that
upstream is its base, not where it publishes. After a verified landing the remote-tracking ref is moved to the proven sha,
and the upstream is set the first time.
Dry run and landing receipts
greengate land --dry-run runs only the first two steps of a land: the branch, its
upstream, and the refusals (detached HEAD, main or master, a dirty tracked
tree, not exactly one push URL). It stops before the remote is read: no
network, no push, no ref written, no receipt. It combines with --force.
--json prints {branch, remote, push_url, pushed, dst, retried, status, receipt_dir, lease}: pushed is the HEAD sha, dst is
refs/heads/<branch on the remote>, retried is always false, lease is
true under --force, and receipt_dir is the directory below. status is
would-land (exit 0) or refused (exit 1, the reason on stderr); the verdict
line is still the last line on stderr.
Every land that is not a dry run writes one receipt,
<git-dir>/amont/land/<started-unix-nanos>-<pid>.json, with the final
outcome: {started, ended, branch, remote, push_url, dst, pushed, retried, status}. It is written for every status once the branch is known (a detached
HEAD has none), and its pushed is the sha the last push attempt carried, so
after a retry it names the retried sha whatever happens to the tracking ref.
The git directory is the worktree's own. A receipt that cannot be written
prints a warning naming the path and does not change the exit code. Receipts
older than seven days are deleted by the next land.
greengate.quiet — say it once, or once per check
git config greengate.quiet never # auto (default) | never | always
A hook that passes prints one line per check, and on a clean run that is the whole output: fourteen lines to say nothing happened. At a terminal those lines are the reassurance that the gate ran at all. Captured — an agent's tool result, a CI log — they are read again on every later turn and say no more the tenth time than the first.
So the setting names who is reading:
| value | effect |
|---|---|
auto | the default: quiet when stderr is not a terminal, verbose when it is |
never | every check says it passed, whoever is reading |
always | quiet everywhere |
Only the success lines go. A failure, a warning, a check that could not
run, a repaired file and the blocked summary print under every setting.
Quiet is about the uneventful path and nothing else — it is not a way to
lose a refusal, and quiet_never_swallows_a_failure pins that.
In their place, one line:
✓ 14 check(s) passed
That count is not decoration. A run that says nothing at all is indistinguishable from a gate that never ran, which is the confusion this whole crate exists to prevent — so quiet gets quieter, never silent.
auto is the default because it is free for the reader it does not help.
At a terminal watching() is true, so committing by hand looks exactly as it
did. What changes is the reader who cannot skim — a captured log, an agent's
tool result — who was paying fourteen lines of nothing on every commit of
every session. Set never to have it back.
One consequence worth knowing: the ✓ N check(s) passed roll-up comes from a
full stage. Running a single check — greengate run pre-commit-yamllint — has no
roll-up to print, so under quiet it succeeds in silence.
greengate.pushStamps — remember what the push gate already proved
git config greengate.pushStamps false # default true
A push-time gate that passes stamps the pushed tips in
refs/notes/greengate-gate, keyed by tree, and the next push of the same content
skips it: the retry after a remote dropped the idle connection mid-suite,
and the git push after an greengate run pre-push rehearsal. Only scoped
gates (test suites) are stamped or skipped, and only for content the suite
actually tested — see "Rehearsing the push gate" on the checks page. false
turns off both the writing and the honouring.
greengate.order — attempt the push gates in the order the record justifies
git config greengate.order evidence # default: declared
declared is the registry's order, and it is what every repository gets
unless it says otherwise. evidence orders the push gates by this
repository's own record of them (refs/notes/greengate-gate, the same notes the
stamps live in): the gates that have actually failed in the last 90 days go
first, ordered by failures per unit of time, so a push that is going to be
refused is refused at minute two instead of minute twenty.
It is an ORDER and nothing else. Every gate still runs, none is assumed to pass, and only the scoped gates — the suites and audits — are permuted: branch-protect, branch-pattern, secrets and pull-rebase keep their positions, because discovering a protected branch after a test suite is the waste this is meant to remove. With no record the declared order is kept exactly. When the order does differ, the push says so.
Settable in a committed greengate.conf (set order evidence) as well as by
git config, because which suite is worth attempting first is a property of
the project. It is the only set key that changes how checks are RUN rather
than what they are — safe on the terms above, and a local git config still
outranks it. See gate evidence.
greengate.commitStamps — do not repeat a commit-time gate on the same tree
git config greengate.commitStamps false # default true
A blocking commit-time gate that already ran clean against exactly the tree
being committed is not run again: the record pre-commit leaves for
post-commit is bound to the tree and survives a commit-msg refusal or a
closed editor, and the stamp post-commit writes on the tree answers for a
reset --soft and re-commit. The reuse is announced in the push gate's
words ("passed on this exact tree earlier"). A changed byte, a changed
declaration, or a gate that failed all run the gate. false turns the reuse
off; the record is still written. See "Moving a gate entry earlier" on the
checks page.
greengate.failFast — skip the heavy checks of a commit already refused
git config greengate.failFast false # default true
Pre-commit runs its Light checks first and starts the Heavy ones (clippy, go
vet, pyright, declared heavy and moved gates) only when no Light check
blocked (ADR-0020).
A Heavy check that would have judged something is reported as skipped,
with an greengate run <name> for each one. It earns no stamp. A passing commit
starts its Heavy checks once the slowest Light check has finished.
<common-dir>/amont-waves records that wait and what was skipped, one line
per commit.
The order, stated once: GREENGATE_FAIL_FAST (true or false, one run), then
git config greengate.failFast (any scope), then a trusted set failFast in
greengate.conf, then on. false runs every check at once, as before 2.1.
greengate.rehearseOnCommit — run the push gate in the background after every commit
git config greengate.rehearseOnCommit true # default false
post-commit starts greengate rehearse for you: a detached worker checks out
HEAD into a throwaway worktree, runs the test gates there — the
push-shaped checks (branch-protect, secrets, the auto-rebase) wait for the
push — and stamps the tree when they pass. By the time you git push, the
suite has usually already run; if it is still running, the push waits for
it rather than starting over. A newer commit cancels a rehearsal of the
older tree, suite and snapshot included, so committing often does not queue
work. Off by default because every commit then costs a suite's worth of CPU
in the background. A finished git rebase starts one too (post-rewrite),
since it leaves no commit on the branch stamped. See "Rehearsing in the background" on the checks page for
what it prints and what greengate rehearse --wait, --status and --stop do.
Needs greengate.pushStamps (the default) — the stamp is the hand-off. Unix
only for now: on Windows a detached child would hold its parent's pipes
until the suite ended, so the hook says so instead and greengate rehearse --wait runs the rehearsal in the foreground.
greengate.rehearsalWait — how long a push waits for a running rehearsal
git config greengate.rehearsalWait 300 # default 300; 0 waits indefinitely
A push that finds a rehearsal of its own tree still running waits for it:
less remaining work than a fresh run, and no extra CPU. That wait happens
after git has opened its connection to the remote, though, so it is the
same idle connection the rehearsal exists to keep short — and it used to be
bounded only by the worker's own greengate.timeout, an hour by default and
unbounded at 0. Five minutes is under every idle timeout we have measured
(Forgejo's git timeout is six), so a wait that expires still leaves the
connection alive for the gate that follows it. When it expires, the gate
runs in the push and the rehearsal is left running — it may still finish and
stamp the tree for next time. greengate rehearse --wait has no budget: nothing
is connected there.
greengate.pushGates — never run a heavy gate on an open connection
git config greengate.pushGates inline # default refuse
git opens its connection to the remote before it runs pre-push, so a test
suite or an audit run there holds the connection for as long as it takes, and
a forge may drop the idle session after every check passed
(ADR-0018). With
refuse, the default since 2.0, a push whose heavy gates (the scoped push
gates its range touches) carry no stamp for the pushed tree is turned away at
once, before any gate starts, naming the gates and how to run them first:
greengate landruns every gate the push owes on a snapshot of the exact commit, with no connection open, then pushes;greengate rehearse --wait(orgreengate run --stamp) stamps the tree, and the push that follows skips the gates.
inline runs them in the push, as before 2.0. A deletion owes nothing, and a
gate that completed earlier without passing is not asked for again while its
record holds: a warning for good, a failure under warn severity while the
gate is still warn, a missing tool for an hour. With greengate.pushStamps false nothing can be stamped, so the refusal names that setting instead of
offering a rehearsal, and greengate land refuses before running anything.
A tag push is refused the same way, and offered greengate land --tag <name>:
it pushes one existing local tag after running, on a snapshot of the tagged
commit, the gates its range owes and, for a v* tag, the release audits. A
tag already on the remote is refused (a tag is never moved), and --dry-run
reports would-land without reading the network.
greengate land --json reports what the pre-stage did in a gates object:
owed (the gates the push owed) and prestage — stamped (nothing left to
run), ran, failed, refused, interrupted, or empty when land stopped
before it. ref is the ref pushed (refs/heads/… or refs/tags/…);
branch is empty for a tag.
greengate.auditMaxAge — how long an audit's record answers
git config greengate.auditMaxAge 24 # hours, 1..720; default 24
The dependency audits (pre-push-audit-{go,js,python,rust}) depend on the
day's advisories, not only on the tree, so they are never stamped. Wherever
one runs on the content being pushed — land's pre-stage, a rehearsal,
greengate run --stamp, an inline push of a clean HEAD — its report is
recorded in refs/notes/greengate-audit (local, never pushed), keyed by the
lockfiles' content for a branch push and by the tree for a v* tag. A push
with a fresh record replays it, judged against today's waivers and that
push's stakes, without running the tool. A record answers for
greengate.auditMaxAge hours; one that could not check anything (offline, tool
missing) for one hour.
greengate.unstampedPush — refuse a push nothing has tested yet
git config greengate.unstampedPush refuse # default run
When a check is declared at both stages and a pushed commit carries no
record of the commit-time run — rewritten by a rebase or an amend, or made
with --no-verify — the push runs the check itself, with git's connection
to the remote held open for as long as the suite takes. That happens only
under greengate.pushGates inline: by default, greengate.pushGates refuse turns the
push away before the check runs, and greengate land runs it first. Under
inline, a long suite can outlive the forge's idle timeout, and the push
fails after passing. There, greengate.unstampedPush refuse turns that push
away at once instead, and says how to earn the stamp with nothing waiting on
it: greengate rehearse --wait, then push again.
A rehearsal of the tree that is still running or has failed is reported the
same way. Pairs with greengate.rehearseOnCommit, which usually earns the stamp
before you push.
greengate.snapshotDeps — how a snapshot gets its JavaScript dependencies
git config greengate.snapshotDeps install # default; or reuse, off
A worktree git just created is a checkout, not a workspace: no
node_modules, and a suite started there fails on Cannot find module
having tested nothing. Every snapshot — the background rehearsal's and
greengate.testPushedTree's alike — is prepared before any suite runs, one
unit at a time: each directory holding a tracked package-lock.json,
pnpm-lock.yaml or yarn.lock, read from the snapshot's own index, so the
pushed commit decides, not HEAD and not what you have staged. A nested
project with a lockfile of its own is its own unit. A directory with more
than one manager's lockfile is settled by package.json's
packageManager, or refused.
A bun.lock or bun.lockb is a unit too, so that a push which does not
touch it is skipped like any other — but greengate does not install bun
dependencies: a unit the push needs fails the preparation with the fix
named, greengate.snapshotPrepare set to the install command, or
greengate.snapshotDeps off. Failing there is deliberate: a gate run over a
checkout with no dependencies fails every workspace at once, and that reads
like a broken branch rather than a missing install.
installdoes what CI does:npm ci --prefer-offline,pnpm install --frozen-lockfile --prefer-offline,yarn install --frozen-lockfile --non-interactive --prefer-offlinefor yarn 1 andyarn install --immutablefor yarn 2+ ("berry"; the committedyarn.locksays which — berry's opens with a__metadata:block — so the pushed commit decides, and each flavour gets the spelling it accepts without a warning). Exact, and it refuses apackage.jsonits lockfile does not satisfy — so does the snapshot.reuse(pnpm and npm) clones the working tree'snode_modulescopy-on-write —clonefile(2)on macOS,cp --reflink=alwayson Linux (btrfs, XFS with reflinks), about 2% of the tree's size in metadata — and never falls back to a plain copy: on another volume or a filesystem that cannot clone, it refuses in one line that names the fix (TMPDIRon the working tree's volume, orsnapshotDeps install) and installs instead. A clone is kept only when the package manager vouches for it against the snapshot's committed manifests and lockfile; any refusal removes every directory cloned for that unit, says why, and installs instead. Before any copy, a lockfile that differs from the commit's refuses, and so does any file in the working tree'snode_modulesnewer than the manager's install record — an edit made after the install, which no manager checks (.bin/,.cache/and.vite*/aside, which installs and tools write afterwards). That rests on timestamps, not content, which is whyreuseis not the default. After the copy, a link that resolves back into the working tree refuses.- pnpm: the root's and each workspace member's
node_modules, aspnpm ls -rlists them; the record isnode_modules/.modules.yaml. The clone must be laid out the way pnpm's isolated linker leaves it (every package a link; a stray directory is refused, since pnpm's own check ignores it and a suite could import it), andpnpm install --frozen-lockfile --offlinemust accept it — which also refuses a manifest the lockfile does not satisfy, and relinks small drift from the store. - npm: the root's
node_modules, and a member's when it has one, asnpm query .workspacelists them; the record isnode_modules/.package-lock.json. Any link in the clone that resolves outside the snapshot refuses (npm link, an absolute link; npm's own relative workspace links stay). The vouch isnpm install --dry-run --offline --ignore-scripts: the clone is kept only when it exits 0, would add, remove and change nothing, and leavespackage-lock.jsonbyte-identical. npm reads the installed tree, not its record (the clone's.package-lock.jsonis removed before the dry-run), so a package whose version was raised in place is caught even with its timestamps set back; a file edited in place without a version change is not, as with pnpm. The JSON is read by a shortnodescript; withoutnodeon PATH the unit installs and says so. Measured on a 25,143-file tree: the clone and the vouch take 43% ofnpm ci's time and 2.5% of its disk. - yarn is never reused: even with the timestamp scan and the link
check, yarn 1's
yarn check --integrityand--verify-treeaccept a tree with a package missing, so nothing yarn offers can vouch for a clone; a yarn unit installs underreusetoo, saying so. Yarn 2+ and bun are not reused either.
- pnpm: the root's and each workspace member's
offprepares nothing.
Only the units the push touches are prepared: the root one, and each unit
that is the nearest enclosing unit of a file changed between the tip and
where it forked from its upstream. The rest are named in one line and
skipped — a repository with side projects of their own (spikes, examples)
no longer pays an install for each on every snapshot. A unit the push does
not touch cannot hold a failure the push introduced; a gate that reaches
into one anyway finds no dependencies and fails loudly, never falsely
passes, and greengate.snapshotPrepare is the override. With no upstream to
measure against, every unit is prepared.
A failed install is the snapshot's failure; see greengate.snapshotPrepare
below for what each caller then does. Nothing is needed for a Rust crate
(cargo resolves from the shared registry; the build is cold, which is the
cost the testPushedTree section describes).
The install runs lifecycle scripts, so a "prepare": "greengate init" runs
inside the snapshot — and the snapshot is a linked worktree, sharing the
repository's hooks directory. To keep that init from baking every hook to
a binary in a temp directory deleted minutes later, the snapshot marks
itself with a greengate-snapshot file in its own git admin dir
(git rev-parse --git-path greengate-snapshot), and greengate init writes nothing
where it finds one; if it cannot tell, it fails rather than guess. Both
halves must be a version carrying this — the greengate that runs the rehearsal
writes the marker, and the greengate the pushed commit's lockfile installs
reads it — so bumping only one of them is not enough. The install and
greengate.snapshotPrepare also get GREENGATE_SNAPSHOT=1, for a custom prepare
script that wants to know; the marker, not the variable, is the guard.
greengate.snapshotCarry — untracked files a snapshot needs
git config greengate.snapshotCarry ".env .npmrc"
or committed, set snapshotCarry .env in greengate.conf. The files a suite
reads and git does not track — a .env, an .npmrc with a registry token —
are copied from the working tree into the snapshot, before the
dependencies, so an install can use them. Only untracked content may be
carried: an entry that is tracked, holds tracked files or sits under a
tracked path would put your uncommitted copy where the commit's belongs, and
the stamp would vouch for a tree nobody committed. Refused too: absolute
paths, ., .. and .git components, and a symlink anywhere on the way —
in the working tree, the snapshot, or inside a carried directory. Every
refusal is listed in one message and fails the preparation; an entry that is
simply absent (no .env in CI) is skipped and said.
greengate.snapshotPrepare — the escape hatch
git config greengate.snapshotPrepare "pnpm prisma generate"
Or committed, so every clone has it:
set snapshotPrepare pnpm prisma generate
in greengate.conf (see custom checks). A local git config still outranks the committed value.
For what greengate cannot know — a code generator, a database client, a build
step. It runs through the shell inside the snapshot after the carry, with
$GREENGATE_SOURCE_WORKTREE naming the working tree the snapshot came from.
When it is set it owns the dependencies: greengate.snapshotDeps stands
down, so a repository whose command already installs does not install twice.
A preparation that fails — carry, install or this command — is the
snapshot's failure, and each caller says so. At push time
(testPushedTree) the gate falls back to the working tree and stamps
nothing for that tip: the suite that then passes never saw the content the
stamp would have vouched for. In a rehearsal the worker records the failure
with its reason (greengate rehearse --status shows it), exits 2, and the next
push treats it as a failed rehearsal.
greengate.autoRebase — whether pre-push may sync a behind branch for you
git config greengate.autoRebase false # default true
On (the default, and the behaviour every install so far has had):
pre-push-pull-rebase rebases a clean, behind, non-diverged branch onto its
own upstream — then stops the push and asks for a second one, because the
refs git handed the hook predate the rebase; the suite would otherwise judge
commits git is no longer pushing, and the server refuses the stale objects
regardless.
Off: the check becomes a pure advisor. It performs no network I/O at all (no
ls-remote, no advisory fetch — behind is judged from your last fetch) and
never runs a rebase you did not type; a behind branch stops the push with the
command to run. A hook that rewrites your branch is a bigger claim than most
teams want a "check" to make — this is the key that unmakes it.
greengate.idleTimeout — how long a check may be silent
git config greengate.idleTimeout 300 # seconds; default 120, 0 disables
A hung tool is silent — a captive portal, a deadlocked lock file, a prompt
nobody will answer. A slow tool talks: cargo test prints a line per test.
So the clock that decides "stuck" counts silence: a command that writes
nothing for this long is killed and the check fails, saying so and naming
this key. Two minutes catches a real hang faster than the old ten-minute wall
clock did, and lets a chatty twenty-five-minute suite finish.
Only commands whose output greengate observes answer to this clock — every
check runs its tools that way by default. With greengate.progress false the
tool inherits your terminal, nobody sees the bytes, and only the ceiling
below applies.
Busy is not stuck
Not every slow tool talks: vitest without a terminal prints its summary and
nothing before it, and a passing suite used to be killed as a hang. So on
Linux and macOS, once a check has been silent for a while (a third of this
budget, at most 30 seconds), greengate also measures the CPU its process tree is
using — the command, its descendants, and the work of every child they have
already reaped. A check keeps its budget as long as that tree does at least
0.1 of a core of work; it is killed only when it has been silent and idle
for the whole budget. A quiet suite then runs on to greengate.timeout, and the
progress line says it is busy (· quiet 2m10s · ~3.9 cores).
The trade-off is written down in ADR-0008: a silent tool that spins — a
busy loop, a polling watcher — now answers to the ceiling rather than this
budget, and the ceiling message says so. Work done by a daemon outside the
tree (a build daemon, a container engine) is not counted. On Windows, or with
greengate.idleCpuCredit false, silence alone counts, and the messages say CPU
was not measured rather than claiming it was idle.
When sampling is on but a measurement is incomplete — the walk came back
partial on a loaded machine, or no sample has landed yet — the check answers
to the extended budget, this budget × greengate.idleLoadScale (eight
minutes by default), never to the bare two minutes: a kill must rest on a
measurement somebody made. One partial snapshot no longer throws the
measurement away; the next complete one spans the gap, may count as busy,
and never as measured idle (ADR-0009).
git config greengate.idleCpuCredit false # silence alone, everywhere
GREENGATE_CPU_TRACE=<file> appends the processes each measurement saw — a
diagnostic for when a check was kept alive, or killed, and you want to know
what greengate was looking at. GREENGATE_CPU_MAX_PROCS=<n> caps the walk, which
forces an incomplete measurement on purpose.
Waiting is not stuck
A tool that is waiting on a lock says so and then says nothing: cargo
prints Blocking waiting for file lock on build directory while another
cargo — a second worktree, rust-analyzer, a build in another session —
holds it, and uv prints Waiting to acquire … lock for …. Those exact lines,
on stderr, pause this clock: the wait answers to greengate.lockWait instead,
and the progress line says · cargo lock 1m30s/10m00s. A check that passes
after such a wait says how long it waited and for what.
A line that only looks like a wait (waiting for lock on …) does not pause
anything. If the silence budget kills a built-in check whose last line read
like that, greengate runs it once more, under what is left of the same ceiling,
and says so; the first kill prints no failure. A declared check is never
retried: a command you wrote may not be safe to run twice.
The silence budget also stretches with the host's load: on a machine whose
one-minute load average is twice its core count, two minutes become four,
up to greengate.idleLoadScale. The progress line and the kill message name
the stretched figure, the load and the key.
Worst case for a genuinely stuck, silent tool, at the defaults:
| situation | killed after |
|---|---|
| CPU measured idle, host not loaded | 2 minutes |
| CPU measured idle, host loaded | up to 8 minutes (idleLoadScale 4) |
| CPU could not be measured | 8 minutes, even with greengate.timeout 0 |
| in a declared cargo or uv lock wait | 10 minutes (greengate.lockWait) |
| retried after a wait-like last line | both attempts inside one greengate.timeout |
| waiting for a host slot | up to greengate.timeout, before it starts |
| anything | greengate.timeout, one hour |
greengate.timeout — the ceiling one check's command may run for
git config greengate.timeout 900 # seconds; default 3600, 0 disables
The backstop behind idleTimeout: a tool that keeps printing and never
finishes is killed here, and the message says whether it was still printing
(slow — raise this) or had gone quiet (stuck — look at the tool). The default
was ten minutes when this was the only clock and had to catch hangs; with
silence doing that job, the ceiling can afford an hour.
The kill reaches the command itself; a grandchild it detached may survive, orphaned, but the commit is no longer hostage to it.
While a stage runs, a terminal shows a live line per check with its elapsed
time, a · quiet 45s/2m note once a check has been silent for half a minute
(· quiet 2m10s · ~3.9 cores instead while its CPU is busy,
· idle 40s/2m counting what the budget counts once busy work has pushed it
back, · cargo lock 1m30s/10m00s during a declared wait, and
· queued 42s (slots 2/2) while it waits for a host slot), and · 50m/1h once it is within 80% of the ceiling — the cliff, shown
before the fall. Piped (an agent, CI), the same information arrives as one
plain line a minute per running check: elapsed, time since its last output,
what its CPU is doing (busy ~3.9 cores, CPU idle 40s, CPU unmeasured),
and, the first time, both budgets.
The same clock bounds the push path's own network verbs: pull-rebase's
sync runs under the full budget, and the reachability probes
(ls-remote before a sync, the initial-push check) under the smaller of
this and 30 seconds — a probe answers in a second or two when the network
is there at all, and a captive portal must not get ten minutes to say
nothing. 0 disables these deadlines too.
greengate.lockWait — how long a check may wait on a lock
git config greengate.lockWait 900 # seconds; default 600, 0 = until the ceiling
How long a tool may sit in a declared lock wait (see "Waiting is not
stuck" above) before it is killed. The kill message names the lock and who
probably holds it. 0 leaves the wait to greengate.timeout; with that off
too, the extended silence budget bounds it, so nothing waits forever.
Settable from greengate.conf (set lockWait 900): how long a workspace's cold
build holds its lock is the project's to know.
Host keys: greengate.idleLoadScale, greengate.hostSlots and greengate.hostCores
These describe the machine, not the repository, so they are read from
--global or --system git config only. A value set in a repository is
ignored, with one warning naming the key and --global; greengate.conf
cannot set them. Precedence, highest first: the environment variable
(GREENGATE_IDLE_LOAD_SCALE, GREENGATE_HOST_SLOTS, GREENGATE_HOST_CORES),
then --global, then --system, then the default. An invalid environment
value is warned about and the next source is read; an invalid git value is
warned about and the default is used.
greengate.idleLoadScale — how far a loaded host stretches the silence budget
git config --global greengate.idleLoadScale 2 # default 4, 1 = never stretch, up to 16
The silence budget is multiplied by the host's one-minute load average over its core count, floored at 1 and capped at this. The same factor sets the extended budget a check answers to while its CPU could not be measured. Linux and macOS read the load; elsewhere the factor is 1.
greengate.hostSlots — how many heavy checks one machine runs at once
git config --global greengate.hostSlots 2 # default: automatic, from the machine; 0 = off
Clippy, go vet, pyright and the test suites compile or execute the
product, and each already uses every core. Several worktrees, sessions or
agents running them at once thrash the same cores and the same cargo lock.
So a heavy check takes one of these slots before its first tool runs, and
waits — its clocks not yet started — while all are taken; the progress line
says · queued 42s (slots 2/2). A check that turns out to have nothing to
do never queues. A check declared in greengate.conf is heavy when its line
carries the heavy marker, or when it moves a built-in heavy gate (its name
is that gate's short name, as pre-commit cargo-test is for
pre-push-cargo-test).
The slots are flock locks on files in /tmp/greenharness-slots-<uid>
($XDG_RUNTIME_DIR/greenharness-slots on Linux when set), a fixed path so every
session shares one queue whatever its $TMPDIR. greengate refuses that
directory unless it is a real directory you own with mode 0700, and then
runs the check unqueued with one line saying why. What a slot that never
frees means is the repository's busy policy:
by default, after greengate.timeout, the check runs unqueued with a note. Waiters are served first come,
first served. A held slot is released when the check ends, and by the kernel
if greengate dies. An greengate started by a check that holds a slot
(GREENHARNESS_HOST_SLOT set) does not queue. Windows has no slots.
Unset, the count follows the machine (ADR-0021): at most half the physical
cores (max(1, cores/2), see greengate.hostCores).
A free slot is taken only while the one-minute load is below the core count,
and at most one new holder is admitted every 60 s. The first waiter on an
empty host always gets one. A number fixes the count, with no load test.
Each holder is also bounded in width: a heavy check or greengate slot run
command runs max(1, weight × cores / cap) jobs, through MAKEFLAGS,
CARGO_BUILD_JOBS, RUST_TEST_THREADS and NEXTEST_TEST_THREADS. The
check's own environment wins, then the parent's, then greengate's computed
width. See docs/host-slots.md.
The same queue serves everything heavy on the machine, not only greengate's
hooks: relais's verification commands, and any command run as
greengate slot run -- <command>. A waiter says whom it waits behind
(queued behind relais: cargo test (amont-wt-x, 4m)), and greengate slots
lists the holders. The protocol is docs/host-slots.md.
greengate.hostCores — the core count the slots are sized from
git config --global greengate.hostCores 12 # default: the physical cores; 1 to 1024
The cap, each holder's width and the admission load test all use one core
count: the physical cores, never more than the logical count. On a 6-core,
12-thread laptop that is 6: 3 automatic slots of 2 jobs, admitted while the
load is below 6. A number replaces it, for a machine where another count
suits better; 12 there restores the sizing from before ADR-0021.
GREENGATE_HOST_CORES overrides it for one process. relais reads the same
key through the slots crate. See docs/host-slots.md.
greengate.onBusy — what a heavy check does on a busy host
set onBusy defer # in greengate.conf; default wait
set slotWait 60 # seconds, 1 to 3600; only under defer
The host keys above say how many heavy checks one machine runs; this one, set by the repository (ADR-0013), says what happens when no slot frees.
-
wait(the default): wait up togreengate.timeout, then run unqueued, with a note. -
defer: wait up toslotWait, then defer the check to CI. It does not run, it never blocks (ablockcheck included), it earns no stamp and it is never attested, so CI's attest step does not list it and CI runs it. The hook says so, with the command to run it now:! 1 check(s) deferred to CI, no host slot freed: pre-commit-cargo-test run now: GREENGATE_ON_BUSY=wait greengate run pre-commit-cargo-test · stop deferring: set onBusy wait
Declare defer only where the repository's CI runs every heavy gate: a
deferred gate is still required, and CI is where it now runs.
Three rules keep defer from deferring work it should not:
- Never behind its own checks. A check defers only when this greengate holds
no slot. Two heavy checks of one commit on an otherwise idle machine wait
for each other, as under
wait. - One wait per push. Once a push gate defers, the later heavy gates of that push defer without waiting again.
- The push twin defers too. A commit-time gate deferred at commit leaves
a
deferred <gate>line on its tree's note. Its pre-push twin (the same name, or the built-in it moves) then defers rather than run the suite with the remote's connection held open. That line can only move a gate to CI, never stamp it.
Precedence, highest first: GREENGATE_ON_BUSY in the environment
(GREENGATE_ON_BUSY=wait git push runs what the file would defer), then
git config greengate.onBusy in the repository, then set onBusy in a trusted
greengate.conf, then --global, then wait: the same ladder as every set
key. A rehearsal (greengate rehearse) always waits: it is how a gate runs
with no push waiting on it. Load from processes outside the hooks holds no
slot and causes no deferral.
greengate.executor — where a platform=any gate runs
set executor cluster # in greengate.conf; default local
set clusterPrepare pnpm install --frozen-lockfile --prefer-offline --ignore-scripts
git config --global greengate.cluster.kubeconfig ~/.config/greengate/kube/homelab.yaml # the file your cluster tooling writes (the homelab: scripts/greengate-gates-kubeconfig.sh)
git config --global greengate.cluster.image 'forgejo.example/gate-runner:1.2.0@sha256:<64 hex>'
A gate declared platform=any (see
custom checks) in a repository whose
trusted greengate.conf says set executor cluster runs as one Kubernetes Job
on the homelab cluster, not on this machine (ADR-0016). It takes no
host slot:
the cluster has its own slots.
The cluster proves only passes. greengate reads the verdict from what
Kubernetes recorded: the Job Complete with no DisruptionTarget, the
prepare and gate containers exited 0, fetch reporting the expected tree,
the pod's imageID. Anything else re-runs the gate here, unchanged, and the
local outcome is the verdict. That covers a gate failure, OOMKilled, a
deadline, a pod not Running within the start wait, a failed prepare, a tree
mismatch, every slot taken or refused by the quota, a bundle over the cap,
kubectl missing or failing, and any of the keys below missing. Each
fallback appends <epoch> <gate> <reason> to greengate/cluster.log in the
common git directory (git rev-parse --git-common-dir). In one hook run,
once the apiserver has failed, the later gates run here without asking it
again.
On the terminal, a clean run says one line, <gate>: running on the cluster. A gate that fails there says <gate> failed on the cluster (exit N); running it here for the verdict, and any other fallback <gate> runs here: the cluster is unavailable (<reason>). A machine with no cluster (the
kubeconfig or the image unset) says nothing, so a repository that sets set executor cluster does not warn on every hook of such a machine; a key that
is set but cannot be used warns once per run and names the fix.
A cluster pass is recorded in refs/notes/greengate-gate-cluster, on the judged
tree, under its own identity: the gate's command and flags, the
clusterPrepare command, the image digest and the version of the cluster
contract. The laptop's own executable is not part of it, so a gate whose tool
exists only in the image is still reused. Changing greengate.cluster.image
makes the gate run again. A cluster pass never becomes a local stamp
(refs/notes/greengate-gate) or a laptop attestation.
The machine keys, read from git config (--global is the usual place):
| Key | Default | Meaning |
|---|---|---|
greengate.cluster.kubeconfig | none: required | The kubeconfig greengate passes as kubectl --kubeconfig. The default context is never used. ~ is expanded. |
greengate.cluster.image | none: required | The gate-runner image, pinned as name:tag@sha256:<digest>. Without @sha256: the gate runs here. |
greengate.cluster.namespace | greengate-gates | The namespace of the Jobs. |
greengate.cluster.slots | 2 | How many Jobs, greengate-gate-slot-0 and up, may run at once. At most 2. |
greengate.cluster.maxBundleMiB | 50 | Above this size, the bundle of the judged tree is not sent and the gate runs here. |
greengate.cluster.startWait | 30 | Seconds the pod has to reach fetch Running before the gate runs here. |
The Job's deadline is greengate.timeout plus 60 seconds, so
greengate.timeout 0 (no ceiling) keeps every gate here. Off switches: unset
greengate.cluster.kubeconfig, or git config greengate.executor local in one
clone, or set executor local in the file.
greengate.rehearse.cluster — a rehearsal that outlives the laptop
# One private repository per project in a snapshot org (greengate-snapshots here).
git config --global greengate.cluster.snapshotRemote 'git@git.example:greengate-snapshots/{repo}.git'
git config --global greengate.cluster.snapshotFetch 'http://forgejo-http.forgejo.svc.cluster.local:3000/greengate-snapshots/{repo}.git'
git config --global greengate.cluster.mirrorRemote 'git@git.example:greengate-snapshots/{repo}-mirror.git' # optional
git config --global greengate.cluster.mirror 'http://forgejo-http.forgejo.svc.cluster.local:3000/greengate-snapshots/{repo}-mirror.git' # optional
git config --global greengate.rehearse.cluster true # default false
greengate rehearse --cluster, or greengate.rehearse.cluster true for the
post-commit rehearsal (greengate.rehearseOnCommit),
sends the gates the rehearsal would run and the cluster may take to one Argo
Workflow, and returns (ADR-0017). A gate goes only if it is platform=any, in
a trusted manifest that says set executor cluster, and nothing vouches for it
on this tree yet; the rest of the rehearsal runs here as before. The command
prints one line per Workflow submitted, with its name and gates, on stderr (stdout stays for asked-for data: --status). Close the lid:
the next commit or push, in any worktree of the repository, collects what
finished into cluster tokens, and the push skips those gates and signs the
x86_64-linux attestation as it does for a Job-lane pass
(greengate cluster collect does it on demand, so does greengate stamps).
The code goes in one of two ways:
- A snapshot. A commit of HEAD's tree with HEAD as its parent, dated now,
pushed with your own git credentials to
refs/snapshots/<run label>ongreengate.cluster.snapshotRemote, then read back withgit ls-remote. A push that is not read back submits nothing: the gates run here andgreengate/cluster.logsays why. - The mirror. When
git ls-remote <mirrorRemote>advertises an object equal to HEAD, nothing is pushed and the cluster fetches that commit fromgreengate.cluster.mirror. Mirror detection is the only thing the laptop does withmirrorRemote, which is why it is its own key rather than a naming convention on the snapshot remote; set both or neither.
In both URL templates {repo} stands for the repository's name: the last
segment of origin's URL, without .git.
| Key | Default | Meaning |
|---|---|---|
greengate.cluster.snapshotRemote | none: required | The URL the laptop pushes the snapshot to. Pushed over ssh with your own credentials; no prompt is ever shown. |
greengate.cluster.snapshotFetch | none: required | The URL the cluster fetches the same repository from (an in-cluster address, http:// only for *.svc.cluster.local). |
greengate.cluster.mirrorRemote | none | The pull mirror's URL as this machine lists it. |
greengate.cluster.mirror | none | The pull mirror's URL as the cluster fetches it. |
greengate.rehearse.cluster | false | The post-commit rehearsal goes detached on its own. |
greengate.cluster.signer | laptop | Who signs the x86_64-linux attestation of a detached pass: laptop, or in-cluster for the block greengate cluster sign writes. Any other value warns once and counts as laptop. |
greengate.cluster.signer-namespace | attest-signer | The namespace of the in-cluster signer's ConfigMaps. |
With none of them set there is no detached lane: a rehearsal is what it was.
The kubeconfig, image, namespace and greengate.timeout are the Job lane's, above;
the Workflow is created as the kubeconfig's user. greengate rehearse --status
shows each pending Workflow's phase and the gates collected, --stop asks the
cluster to terminate them, and kubectl get wf -n greengate-gates follows a run.
What a pass needs. Collect reads the pod, not the Workflow: fetch
terminated 0 reporting the expected tree, prepare 0 when set, main
terminated 0, an imageID, no disruption, from a pod owned by the Workflow
greengate created and running the image and command it submitted. A Workflow or
node that says Succeeded while main exited 1 is no pass. The token written
is the one worked out at submission: change the command, clusterPrepare or the
image after submitting and the push does not accept the pass, it runs the gate.
Anything else writes one line in greengate/cluster.log and nothing more.
The in-cluster signer. With greengate.cluster.signer in-cluster, collect
also asks the signer namespace, once per cluster, for the ConfigMaps of the
pending runs (greengate.signer=block). A Workflow's block is checked with
greensummit against the repository's allowed_signers (the one a push
verifies with, which must list cluster-signer@x86_64-linux): one block,
platform x86_64-linux, the record's tree, every gate that passed, signed by
a principal bound to x86_64-linux. It is then filed in the local
refs/notes/greensummit under the tree, and the next push publishes that
block instead of signing the linux block itself. A block not written yet keeps
the run pending ("signer":"awaiting") until the Workflow's TTL; a refused or
skipped block, a signer that never answers, or a tree with no filed block is
signed by the laptop at the push, as with laptop. A push never waits for the
signer. A filed block lives in the local notes ref until a push publishes it:
a later sync of that ref from origin (greengate stamps, a push of another
tree) drops it, and the laptop signs instead.
greengate cluster collect exits 0 when it asked the cluster (or another collect is
already running, which it says), and 1 when the cluster was not reached or the
pending file could not be written; rehearse --stop exits 1 when a Workflow
could not be terminated and prints the kubectl patch that does it by hand.
rehearse --status also lists the runs that ended since the last look, with the
gates that did not pass.
The record of what is pending is $GIT_COMMON_DIR/greengate/cluster-pending;
deleting it forgets the Workflows, and refs/snapshots/* on the remote are
pruned by the cluster. Unix only.
greengate cluster sign — the in-cluster signer
greengate cluster sign [--watch] runs in a pod in the cluster, not on a
laptop. It signs finished detached runs from what Kubernetes recorded. Each
pass makes one batched read of the Workflows and pods carrying greengate.run
in greengate-gates. It considers a Workflow that is
finished, has no ConfigMap yet, and was submitted by greengate: it carries its
tree and gate ids as greengate writes them. Each gate is judged on its pod with
the same rules as collect's, above. Only a pod that the Workflow owns, by
ownerReferences and by its own node record, counts. A Job's pod, or a pod
wearing a borrowed run label, counts for nothing.
The gates that passed go into one signed greensummit block for
platform x86_64-linux, with no input lines. The block is written to a
ConfigMap named after the Workflow, under data.block, in the signer
namespace. The ConfigMap is labelled greengate.run and
greengate.signer=block, and annotated with the Workflow's namespace, the tree
and an expiry 7 days out. When no gate passed, the ConfigMap holds an empty
block and the reason, under data.skipped, so the Workflow is not judged
again. A ConfigMap that already exists counts as done. A pod not listed yet,
or whose status cannot be read, holds the Workflow for a later pass while it
finished 5 minutes ago or less; after that it is skipped like the rest. Each
pass also deletes the expired ConfigMaps. It logs how many finished Workflows
older than 5 minutes still have none.
After each pass it writes <unix-seconds> clean or <unix-seconds> failed
to $HOME/heartbeat. A liveness probe can read the time to tell that the
loop turns, and the word to tell a live signer whose passes fail.
| Variable | Default | Meaning |
|---|---|---|
GREENGATE_SIGNER_KEY | none: required | The ed25519 private key it signs with, checked once at start. The principal is the verifier's allowed_signers business. |
GREENGATE_SIGNER_KUBECONFIG | none | A kubeconfig. Without it, kubectl uses the pod's ServiceAccount. |
GREENGATE_SIGNER_NAMESPACE | attest-signer | Where the ConfigMaps are written. |
It writes one plain line on stderr per Workflow it acts on:
signed <workflow> <gate,…> tree <short>, skipped <workflow>: <reason>,
or error <workflow>: <reason>. Stdout stays empty, except for the usage
that -h or --help prints, with exit 0.
Without --watch it does one pass and exits:
- 0: the pass was clean.
- 1: the pass failed: the cluster could not be read, or signing or writing a ConfigMap failed.
- 2: a usage or configuration error: an unknown option, or
GREENGATE_SIGNER_KEYunset or not a usable private key (the line names the path and why).
With --watch it runs a pass every 30 s. A failed pass is logged and the loop
goes on. The first SIGTERM or SIGINT is said on stderr (stopping after the current run (SIGTERM)). It lets the run in progress finish: the stop is
noticed before the next kubectl call, so within one call (20 s). The runs left
unrecorded are judged again on the next start. The process then says
stopped: SIGTERM after the current run and exits 0 after SIGTERM (the pod's
graceful stop), or 130 after SIGINT. A second signal of either kind ends the
process at once, killed by that signal.
greengate.minVersion — the greengate this repository means
git config greengate.minVersion 1.11.0
Rarely set by hand — the committable spelling is set minVersion 1.11.0
in a trusted greengate.conf,
which is the point: a binary one release behind answers every hook name
and simply lacks a check, silently, and nothing in the repository could
say which greengate the team meant. A binary older than the floor gets one
warning line per stage naming both versions. Warn-only, deliberately:
blocking commits for being out of date teaches --no-verify, and a
binary too old to know this key cannot honour it anyway.
greengate.knownIdentity — identities usual-name has vouched for
Written by the tool, not by you: when pre-commit-usual-name finds your
user.name <user.email> in history once, it records the identity here
(local config, never committed) and never walks the full history for it
again — git shortlog --all on every commit is milliseconds today and a
scale cliff on a long history. Multi-valued; greengate uninstall removes it
with the rest of greengate's bookkeeping. Delete a value to make the check walk
again.
greengate.fix — let a check repair what it finds
git config greengate.fix true
Off unless you ask. A hook that edits your files without being asked is a larger surprise than one that complains. See custom checks.
greengate.planExempt — reusing gates across a plans-only commit
set planExempt off in a committed greengate.conf turns off the canonical-tree
route (attest 1.5.0): a result is then reused only on the exact tree, or by a
spec's declared inputs. It exists for a repository whose gate reads the
contents of a plan, which the canonical route would otherwise skip when only
a plan changed.
- The default is on; the value is exactly
onoroff, and the line appears once. Anything else (off # because, a second line) is a broken line, because attest's verifiers read this one line from the committed bytes with a reading that matches only exactlyset planExempt off, and a shape they would read as "on" must not look like "off" here. offonly narrows what is reused, so it is honoured trusted or not, and by every producer and verifier, CI included. An unreadablegreengate.confcounts as off.- Because
greengate.confis part of the canonical tree, adding or removing the line changes the fingerprint and the next push runs everything once. - Deprecated as the opt-out's home (attest 1.6.0, decisions ADR-0037): the
opt-out is now
@plan-exempt offin.github/greensummit-inputs(or.forgejo/), attest's own file, so attest reads no other tool's configuration. Until attest 2.0.0 write both lines: verifiers before attest 1.6.0 know only this one.greengate listsays so on stderr while only this line is present. A repository whosegreensummit-inputsalready declares gates adds the directive only once its CI pins attest 1.7.0 or later and itsgreengate.confsetsminVersion 1.58.0, because to older tools the directive invalidates the spec.
greengate.testPushedTree — test what you are pushing
git config greengate.testPushedTree true
By default pre-push runs your suite against the working tree, and says
so. That is fast and usually what you want, but it is not what you are pushing:
an uncommitted fix makes a broken commit look green.
With this set, the suite runs in a throwaway checkout of the commits being
pushed, and your tree is not touched. This covers every pre-push gate that
runs a suite — the built-ins and any pre-push line in your greengate.conf
alike, each once per pushed ref. It costs a second checkout and a build
that cannot reuse your target/ cache, which is why it is opt-in rather than
the default. A checkout that needs a step before it can run anything — a
pnpm install, say — names it in greengate.snapshotPrepare, above.
greengate.attest / greengate.attestKey — sign what pre-push proved, for CI
git config greengate.attest true
Off by default. With it on, a push whose pre-push block gates all passed
leaves an ssh-keygen-signed note on each pushed tip in
refs/notes/greensummit — binding the pushed tree, the names of the
gates that passed, and the greengate version — and pushes that ref to the same
remote, so CI can verify the note and skip the test steps it names.
greengate.attestKey points at the signing key; unset, it means
~/.ssh/greengate-attest. The verifying side, the trust statement being made,
and why every failure falls back to CI running the tests are in
the CI backstop.
greengate.trusted
Set by greengate trust, read by everything that decides whether a declared
external may run. --local only, never committed. Do not set it by hand — see
the trust model.
commit.template
Not ours, but worth setting: it puts the footer scaffold in front of you when you write a commit.
git config --global commit.template ~/.config/git/git-templates/message
Environment variables
| variable | effect |
|---|---|
GIT_HOOKS_BIN | Absolute path to the binary a shim should use. First candidate in the shim's resolution order. |
GREENGATE_BIN_DIR | Where greengate install and the installer script put binaries. Default ~/.local/bin. |
GREENGATE_VERSION | Pins the version the installer script fetches. |
GREENGATE_ATTEST_PUSH | Set by greengate itself on the notes push greengate.attest makes, so the recursive pre-push stands down. Not for humans. |
GREENGATE_FAIL_FAST | false runs this commit's checks in one wave, true in two; outranks greengate.failFast. |
NO_COLOR | Honoured, as is a non-tty stdout: output to a pipe, a file or a CI log carries no colour. TERM=dumb too. |
FORCE_COLOR | Colour through a pipe anyway, for a caller that renders it (non-empty, not 0 or false). NO_COLOR and TERM=dumb still win. |
Repository-declared checks
A repository can add checks of its own without anybody forking anything, in a
committed greengate.conf. They obey every control on this page, addressed the
same three ways, and they are inert until trusted.
Full reference: custom checks · the trust model.
Seeing the result
greengate list # what would run here, and why not
greengate list --json # the same, machine-readable
greengate setup # walk the commit-style keys, with the current values
greengate-fleet # the same, across every repository
greengate list ends with the commit style in effect, and names the key and the
scope of anything you set:
commit style
gitmoji suffix greengate.commit.gitmoji (global)
subject max 72
description max 68 greengate.commit.descriptionMax (global)
body wrap off greengate.commit.bodyWrap (local)
`greengate setup` to change any of these
greengate list reports the effective severity, after overrides — so a
check you downgraded three months ago is visible as downgraded rather than
having to be inferred from config. Across a fleet, greengate-fleet shows
skips and severities per repository, with TRIGGER as its own column.