> ## Documentation Index
> Fetch the complete documentation index at: https://jonathansantilli-codegate-92.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```json theme={null}
{
  "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:

```json theme={null}
{
  "severity_threshold": "critical"
}
```

To fail on any finding including `info`:

```json theme={null}
{
  "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:

```bash theme={null}
#!/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`):

```bash theme={null}
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.

```yaml theme={null}
- 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:

```yaml theme={null}
- name: Run CodeGate
  run: codegate scan . --no-tui --format sarif --output codegate.sarif
  continue-on-error: true
```

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

See [CI/CD with GitHub Actions](/integrations/ci-github-actions) for full workflow examples including SARIF upload.