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:

keyreaches
pre-commit-clippythat one check
clippythat check, on either trigger
pre-commitevery 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:

keydefaultmeans
greengate.commit.gitmojinonewhere the type's emoji goes
greengate.commit.subjectMax72longest the whole subject may be
greengate.commit.descriptionMax50longest the part after type: may be
greengate.commit.bodyWrap72column 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
nonefeat: add a cartthe default — your subject, untouched
prefix✨ feat: add a cart
suffixfeat: add a cart ✨commitlint and changelog tools still see the type
replace✨ add a cartthe 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.

exitstatusmeaning
0landedthe remote ref equals the pushed sha
1refuseda hook, the server, or a precondition said no (including more than one push destination)
2usagewrong invocation (also printed as a status under --json)
3unreachable, unverifiedthe remote could not be read, or the push was accepted and could not be read back
4not-observedaccepted, but the expected tip was not observed; remote_after holds what was
128+ninterruptedkilled 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:

valueeffect
autothe default: quiet when stderr is not a terminal, verbose when it is
neverevery check says it passed, whoever is reading
alwaysquiet 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 land runs every gate the push owes on a snapshot of the exact commit, with no connection open, then pushes;
  • greengate rehearse --wait (or greengate 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.

  • install does what CI does: npm ci --prefer-offline, pnpm install --frozen-lockfile --prefer-offline, yarn install --frozen-lockfile --non-interactive --prefer-offline for yarn 1 and yarn install --immutable for yarn 2+ ("berry"; the committed yarn.lock says 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 a package.json its lockfile does not satisfy — so does the snapshot.
  • reuse (pnpm and npm) clones the working tree's node_modules copy-on-write — clonefile(2) on macOS, cp --reflink=always on 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 (TMPDIR on the working tree's volume, or snapshotDeps 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's node_modules newer 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 why reuse is 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, as pnpm ls -r lists them; the record is node_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), and pnpm install --frozen-lockfile --offline must 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, as npm query .workspace lists them; the record is node_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 is npm install --dry-run --offline --ignore-scripts: the clone is kept only when it exits 0, would add, remove and change nothing, and leaves package-lock.json byte-identical. npm reads the installed tree, not its record (the clone's .package-lock.json is 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 short node script; without node on PATH the unit installs and says so. Measured on a 25,143-file tree: the clone and the vouch take 43% of npm 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 --integrity and --verify-tree accept a tree with a package missing, so nothing yarn offers can vouch for a clone; a yarn unit installs under reuse too, saying so. Yarn 2+ and bun are not reused either.
  • off prepares 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:

situationkilled after
CPU measured idle, host not loaded2 minutes
CPU measured idle, host loadedup to 8 minutes (idleLoadScale 4)
CPU could not be measured8 minutes, even with greengate.timeout 0
in a declared cargo or uv lock wait10 minutes (greengate.lockWait)
retried after a wait-like last lineboth attempts inside one greengate.timeout
waiting for a host slotup to greengate.timeout, before it starts
anythinggreengate.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 to greengate.timeout, then run unqueued, with a note.

  • defer: wait up to slotWait, then defer the check to CI. It does not run, it never blocks (a block check 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):

KeyDefaultMeaning
greengate.cluster.kubeconfignone: requiredThe kubeconfig greengate passes as kubectl --kubeconfig. The default context is never used. ~ is expanded.
greengate.cluster.imagenone: requiredThe gate-runner image, pinned as name:tag@sha256:<digest>. Without @sha256: the gate runs here.
greengate.cluster.namespacegreengate-gatesThe namespace of the Jobs.
greengate.cluster.slots2How many Jobs, greengate-gate-slot-0 and up, may run at once. At most 2.
greengate.cluster.maxBundleMiB50Above this size, the bundle of the judged tree is not sent and the gate runs here.
greengate.cluster.startWait30Seconds 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> on greengate.cluster.snapshotRemote, then read back with git ls-remote. A push that is not read back submits nothing: the gates run here and greengate/cluster.log says why.
  • The mirror. When git ls-remote <mirrorRemote> advertises an object equal to HEAD, nothing is pushed and the cluster fetches that commit from greengate.cluster.mirror. Mirror detection is the only thing the laptop does with mirrorRemote, 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.

KeyDefaultMeaning
greengate.cluster.snapshotRemotenone: requiredThe URL the laptop pushes the snapshot to. Pushed over ssh with your own credentials; no prompt is ever shown.
greengate.cluster.snapshotFetchnone: requiredThe URL the cluster fetches the same repository from (an in-cluster address, http:// only for *.svc.cluster.local).
greengate.cluster.mirrorRemotenoneThe pull mirror's URL as this machine lists it.
greengate.cluster.mirrornoneThe pull mirror's URL as the cluster fetches it.
greengate.rehearse.clusterfalseThe post-commit rehearsal goes detached on its own.
greengate.cluster.signerlaptopWho 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-namespaceattest-signerThe 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.

VariableDefaultMeaning
GREENGATE_SIGNER_KEYnone: requiredThe ed25519 private key it signs with, checked once at start. The principal is the verifier's allowed_signers business.
GREENGATE_SIGNER_KUBECONFIGnoneA kubeconfig. Without it, kubectl uses the pod's ServiceAccount.
GREENGATE_SIGNER_NAMESPACEattest-signerWhere 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_KEY unset 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 on or off, 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 exactly set planExempt off, and a shape they would read as "on" must not look like "off" here.
  • off only narrows what is reused, so it is honoured trusted or not, and by every producer and verifier, CI included. An unreadable greengate.conf counts as off.
  • Because greengate.conf is 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 off in .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 list says so on stderr while only this line is present. A repository whose greensummit-inputs already declares gates adds the directive only once its CI pins attest 1.7.0 or later and its greengate.conf sets minVersion 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

variableeffect
GIT_HOOKS_BINAbsolute path to the binary a shim should use. First candidate in the shim's resolution order.
GREENGATE_BIN_DIRWhere greengate install and the installer script put binaries. Default ~/.local/bin.
GREENGATE_VERSIONPins the version the installer script fetches.
GREENGATE_ATTEST_PUSHSet by greengate itself on the notes push greengate.attest makes, so the recursive pre-push stands down. Not for humans.
GREENGATE_FAIL_FASTfalse runs this commit's checks in one wave, true in two; outranks greengate.failFast.
NO_COLORHonoured, as is a non-tty stdout: output to a pipe, a file or a CI log carries no colour. TERM=dumb too.
FORCE_COLORColour 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.