Exit codes

0  no findings at or above the configured threshold
1  findings at or above the threshold
2  Gate itself failed

The codes

Name
0
Type
pass
Description
The scan completed and nothing met the failure threshold. This includes a repository with no agent configuration at all.
Name
1
Type
findings
Description
The scan completed and found something at or above --severity. This is a real result, not an error.
Name
2
Type
error
Description
Gate could not do its job: a malformed config file, an invalid --severity, a missing --config path, a corrupt baseline, or an internal crash.

Why 2 exists

Because CI needs to tell "your agent is dangerous" from "Gate broke", and a single non-zero code cannot.

Without the distinction, a typo in gate.config.ts looks exactly like a critical security finding. Teams debug it once, discover it was a config error, and start treating red Gate builds as probably-noise. That is how a security check stops working while continuing to run.

Handling them separately

gate scan --severity high
status=$?

case $status in
  0) echo "clean" ;;
  1) echo "findings - read the summary" ;;
  2) echo "Gate itself failed - this is a build problem, not a security one"; exit 2 ;;
esac

The GitHub Action does this for you: exit code 2 becomes a build error with a distinct message, not a security annotation.

Controlling the threshold

gate scan --severity critical   # only critical fails the build
gate scan --severity high       # default
gate scan --severity medium     # once you have dealt with the backlog

gate.config.ts

export default defineConfig({ severity: 'high' })

The flag wins over the config file, so a pipeline can be stricter than a developer's laptop without editing anything.

Never masking a failure

# Do not do this.
gate scan || true

If the goal is to adopt Gate without failing builds on pre-existing findings, use a baseline with fail-on-new-only. That keeps the check meaningful while still letting you merge. || true turns Gate into decoration.