Policy gate — guard
A declarative merge gate that caps how many findings of each severity a change may carry, via an opt-in .commitbrief/policy.yml. Richer than a single --fail-on threshold; aimed at gating high-volume, often AI-authored, pull requests.
commitbrief guard is a declarative merge gate. Instead of one
severity cutoff, it evaluates a review’s actionable findings against a
.commitbrief/policy.yml and exits non-zero when the policy is
breached. Think of it as a per-severity budget rather than the single
--fail-on=<severity> threshold — useful when you’re gating
high-volume, often AI-authored, pull requests.
The policy file
The gate is opt-in in the sense that nothing runs it until you
call commitbrief guard. Once you do, a .commitbrief/policy.yml must
exist: with no policy file guard fails with exit code 1 instead of
passing. Create one to declare the budget:
# .commitbrief/policy.yml
version: 1
thresholds: # max findings allowed per severity (omit or ~ = unlimited)
critical: 0
high: 0
medium: 5
low: ~
total: 20 # optional overall cap across all severities
A severity you omit (or set to ~) is unlimited. total is an
optional cap on the combined count.
rules — deny and allow by rule
Requires v1.19.0 or later. Every finding carries a rule id
from a closed list of 30. The optional rules block turns a class of
finding into a hard stop, or waives one from the budget:
version: 1
thresholds:
high: 0
medium: 5
rules:
deny:
- sec.* # any security finding blocks the merge
- test.flaky
allow:
- style.* # style findings never count toward the budget
| List | Effect |
|---|---|
deny | Each matching finding is a violation named rule:<id>, with allowed 0 and actual 1, regardless of thresholds. |
allow | Matching findings are waived: they leave the per-severity counts and total, and are reported as waived. |
Deny wins over allow: a finding matching both is denied. Entries are a
taxonomy id (sec.injection) or a whole category (sec.*). Nothing
else is accepted. A bare category (sec), a partial glob (sec.in*),
an unknown id, the same id in both lists, or an unknown key under
rules is a hard error and the gate fails, in line with the rule that
a gate which cannot read its policy does not pass.
A finding with no rule id, such as JSON from an older binary read with
--from-json, counts as general.other. A policy without a rules
block behaves exactly as before.
allow removes a finding from the gate, not from the review. It still
appears in the review output; only the verdict ignores it. Unlike a
baseline, which is user-private, the
policy file is committed and reviewed with the code.
Two ways to run it
Run-mode — review, then evaluate
Run-mode reviews the diff (reusing the standard pipeline) and judges the result against the policy:
commitbrief guard # staged diff
commitbrief guard --unstaged
commitbrief guard --diff main...HEAD
Consume-mode — evaluate an existing review
--from-json evaluates a review you already produced, with no
provider call — so an agent’s MCP self-review
or a prior commitbrief --json run can be gated cheaply:
commitbrief --json --staged > review.json
commitbrief guard --from-json review.json
--from-json - reads the review from stdin — which is also how a
credential audit gets gated, since leaks --json
emits the same schema-v1 document:
commitbrief leaks --json --fail-on none | commitbrief guard --from-json -
There was no model call in that pipeline (meta.provider is
"builtin", cost_usd is 0), and guard neither knows nor cares.
What it evaluates
guard judges the findings that survive
baseline + suppression (signal control)
— exactly the set --json shows. Baselined and inline-suppressed
findings are already gone before the policy sees them.
Exit codes
The exit code is 0 (pass) or non-zero (blocked). Critically, a load or parse failure also blocks: a missing or malformed policy, or an unparseable review, fails the gate rather than passing it — a merge gate must not pass when it cannot prove the change is within policy.
The same holds when the model response could not be parsed into
structured findings, whether the review ran live, was replayed from the
cache, or arrives through --from-json. guard then exits 1 with a
“policy cannot be verified” error, prints no verdict, and --json writes
no verdict document; re-run the review, or add --no-cache if a cached
result was replayed. A healthy review with no findings still passes.
Requires v1.21.1 or later; earlier versions passed in that case unless
--sarif was set.
--json emits a machine-readable verdict:
{
"passed": false,
"counts": { "critical": 0, "high": 2, "info": 0, "low": 0, "medium": 1 },
"total": 3,
"violations": [
{ "severity": "high", "allowed": 0, "actual": 2 }
],
"waived": 0
}
counts always carries all five severities. Each entry in violations
names the breached severity (or total for the overall cap), the
allowed maximum, and the observed count; severity violations come in
critical to info order, with total last, then any rule:<id> violations in alphabetical
order. waived (Requires v1.19.0 or later) counts findings removed by
rules.allow.
On the terminal, the verdict adds one line per denied rule and a waiver summary:
rule sec.injection: denied by policy (2 findings)
Waived by policy rules.allow: 3 finding(s)
A single denied finding prints rule X: denied by policy without the
count. In run-mode, signal-control warnings (for example an unknown
inline marker token) go to stderr and respect --quiet.
SARIF output
Requires v1.21.0 or later. guard --sarif writes a SARIF 2.1.0 log
under the commitbrief/guard/ category for GitHub Code Scanning. Use
-o to write a file; the verdict goes to stderr and the exit code is
unchanged.
commitbrief guard --sarif -o guard.sarif
The log holds only the findings that cause a violation. It is built
from the same set the verdict is computed from, so the log and the exit
code cannot disagree. A passing run writes a valid log with
results: [].
It fails closed. When the model response could not be parsed into
structured findings, in run-mode or in a --from-json input, no file is
written and the command exits 1; re-run the review. Upload it with
category: commitbrief/guard. See
SARIF and Code Scanning.
guard vs. --fail-on
--fail-on=<severity> is the simple
one-threshold gate — “fail if any finding meets or exceeds this
severity.” guard is the per-severity budget — “allow up to N of each.”
They complement each other; use either or both. A repo might run
--fail-on=critical on a developer’s pre-commit hook and the richer
guard policy on the CI merge gate.
Flags
| Flag | Notes |
|---|---|
--policy <path> | Policy file location. Default .commitbrief/policy.yml, resolved relative to the repo root. An explicit --policy path is used as given, relative to the current working directory. |
--from-json <file|-> | Consume-mode: evaluate a prior schema-v1 review (no provider call). - reads stdin. |
--unstaged | Run-mode: review the working tree instead of the staged diff. |
--diff <range> | Run-mode: review an arbitrary git diff range. |
--json | Emit the machine-readable verdict. |
--sarif | Write the findings that breach the policy as a SARIF 2.1.0 log. Requires v1.21.0 or later. See SARIF output. Not with --json, --markdown, --suggest-commit, --cli or --show-prompt. |
--provider / --model / --no-flaky carry over from the persistent
flags in run-mode, as do the path filters (--file, --dir,
--exclude-file, --exclude-dir) and the
commit filters
(--author, --committer, --start-date, --end-date, --text,
--max-commits, --merges).
Sandbox-rerun never runs under
guard. Even withreview.sandbox_commandconfigured, the gate will not execute your repository’s tests — unconditionally, with no toggle. Its flaky findings stay at the static-only confidence level. See Flaky-test detector.
See also
- Gate CI on review findings — a guided
walkthrough of
--fail-onandguardin CI. - Severity and CI gating —
--fail-on, the simpler one-threshold gate guard complements. - Signal control — baseline + suppression, the filters applied before guard evaluates.
- MCP server — produce a review an agent can
feed to
guard --from-json. - Output formats — the JSON schema v1 that consume-mode reads.