The gate and branch protection

Postil completes two check-runs on every reviewed PR. They have different jobs and must never be conflated.

The two checks

Requiring the gate

1. Repository Settings → Branches → Branch protection rules (or a ruleset) for your default branch.
2. Enable Require status checks to pass before merging.
3. Add postil/gate to the required checks. Do not add postil/review — advisory findings should inform, not block.

With this in place, a PR with an error-severity finding cannot merge until the finding is fixed (the next push re-reviews incrementally and resolves it) or the threshold is deliberately changed in config — a reviewable, auditable act.

Choosing a threshold

# .postil.yaml
gate:
  failOn: error   # default: block only on error-severity findings
  # failOn: warn  # stricter: block on warnings too

The default blocks only on error: findings the model is confident affect correctness, security, or data integrity. Warnings and informational findings stay in the advisory check where they cannot stop a merge. This is the missing primitive the category has: teams that wanted "block on critical, ignore nits" previously had to accept blocking on everything or nothing.

Fail-closed semantics

If the review crashes, times out (10-minute watchdog), or the model returns garbage, postil/gate completes as failure with the operational error in the summary. It is never left in-progress and never marked neutral. An unreviewed head is not a passing head; pushing again or re-requesting the check re-runs the review.

Repos that prefer fail-open over a blocked merge queue during a model outage can set gate.onError: advisory, which fails open on provider outages only; the default remains block. See configuration.

Local parity

The same gate runs locally: postil review --staged exits 1 exactly when the hosted gate would fail, so a pre-push hook (postil hook install) gives you the verdict before CI does. Preview threshold changes with postil plan.