Exit codes

Understand the four exit codes CodeGate returns and how to use them in shell scripts and CI pipelines to gate on findings.

CodeGate exits with a numeric code after every scan. The exit code tells you whether findings exist and whether they cross the configured severity threshold. CI systems, shell scripts, and pipeline orchestrators can read this code to decide whether to block, warn, or continue.

Exit code reference

Code	Meaning
0	No unsuppressed findings
1	Findings exist, all below severity_threshold
2	One or more findings at or above severity_threshold
3	Scanner or runtime error

Code 0 — No unsuppressed findings

The scan completed and found nothing above, at, or below the threshold that has not been suppressed. This is a clean result.

Suppressed findings (via suppress_findings or suppression_rules in config) do not affect the exit code. A scan with only suppressed findings exits 0.

Code 1 — Findings below threshold

Findings were detected, but none of them reach the configured severity_threshold. The default threshold is high, so a scan that finds only medium and low severity issues exits 1.

In codegate run mode, exit code 1 allows tool launch to proceed unless auto_proceed_below_threshold is false in config.

Code 2 — Findings at or above threshold

At least one finding matches or exceeds the configured severity_threshold. This is the blocking exit code. Use it to fail CI jobs and block deployments.

In codegate run mode, exit code 2 blocks the tool from launching.

Code 3 — Scanner or runtime error

CodeGate encountered an internal error before or during scanning. This is not a “no findings” result. Treat exit code 3 as a pipeline failure and inspect the run log.

Relationship to severity_threshold

The severity_threshold configuration key determines the boundary between exit code 1 and exit code 2. It defaults to high.

{
  "severity_threshold": "high"
}

Severity levels from lowest to highest: info, low, medium, high, critical.

With the default high threshold:

• A critical or high finding → exit code 2
• A medium, low, or info finding (only) → exit code 1

To raise the bar and only block on critical findings:

{
  "severity_threshold": "critical"
}

To fail on any finding including info:

{
  "severity_threshold": "info"
}

Set the threshold in ~/.codegate/config.json (global) or <project>/.codegate.json (project-level). CLI flags do not override severity_threshold directly; adjust the config file or use suppression_rules to tune the effective signal.

Using exit codes in shell scripts

A minimal gate script:

#!/usr/bin/env bash
set -euo pipefail

codegate scan . --no-tui --format json --output codegate.json
EXIT=$?

case $EXIT in
  0)
    echo "Clean scan. No findings."
    ;;
  1)
    echo "Findings detected below threshold. Review codegate.json."
    # Non-blocking: allow the script to continue.
    ;;
  2)
    echo "Blocking findings detected. Review codegate.json before proceeding."
    exit 2
    ;;
  3)
    echo "Scanner error. Check the output above."
    exit 3
    ;;
esac

To fail on any finding (exit code 1 or 2):

codegate scan . --no-tui
EXIT=$?

if [ $EXIT -ne 0 ]; then
  echo "Findings or error (exit $EXIT). Halting."
  exit 1
fi

Using exit codes in CI

In GitHub Actions, any step that exits with a non-zero code fails the job. Exit code 2 fails the job automatically—no extra configuration needed.

- name: Run CodeGate
  run: codegate scan . --no-tui --format sarif --output codegate.sarif
  # Exit code 2 (blocking findings) fails this step and stops the job.

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  if: always()   # Upload even when the scan step fails so findings appear in Code Scanning.
  with:
    sarif_file: codegate.sarif

Use if: always() on the upload step so SARIF results are published even when the scan exits 2.

To allow the pipeline to continue despite findings and only report:

- name: Run CodeGate
  run: codegate scan . --no-tui --format sarif --output codegate.sarif
  continue-on-error: true

Use continue-on-error: true only for reporting-only pipelines. For blocking gates, omit it and let the exit code fail the job.

See CI/CD with GitHub Actions for full workflow examples including SARIF upload.