CI/CD integration

Save scan and eval results as build artifacts to prove validation before deployment.

API keys required. Add your LLM provider API key (Gemini, OpenAI, or Anthropic) to your CI system’s secrets/environment variables. Never commit API keys to your repository.

Install OpenGrep in your pipeline. switch-trust scan uses OpenGrep for pattern analysis, and pip install switch-trust-cli doesn’t include it. Without it, the scan writes its results file and then exits 26, naming the missing tool, so the build fails. Each example below installs it and puts it on PATH.

GitHub Actions
GitLab CI
CircleCI

Add switch-trust-cli to your GitHub Actions workflow:

name: Agent validation

on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.11'
      
      - name: Install switch-trust-cli
        run: pip install switch-trust-cli
      
      - name: Install OpenGrep
        run: |
          curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash
          echo "$HOME/.opengrep/cli/latest" >> "$GITHUB_PATH"
      
      - name: Scan agent code
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: switch-trust scan ./agent --output scan-results.json
      
      - name: Upload scan results
        uses: actions/upload-artifact@v7
        with:
          name: switch-trust-scan-results
          path: scan-results.json

GitHub Actions documentation →

Add switch-trust-cli to your .gitlab-ci.yml:

stages:
  - validate

scan-agent:
  stage: validate
  image: python:3.11
  script:
    - pip install switch-trust-cli
    - curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash
    - export PATH="$HOME/.opengrep/cli/latest:$PATH"
    - switch-trust scan ./agent --output scan-results.json
  artifacts:
    paths:
      - scan-results.json
    expire_in: 30 days
  variables:
    GEMINI_API_KEY: $GEMINI_API_KEY

The artifact is automatically attached to your merge request.GitLab CI documentation →

Add switch-trust-cli to your .circleci/config.yml:

version: 2.1

jobs:
  scan:
    docker:
      - image: cimg/python:3.11
    steps:
      - checkout
      
      - run:
          name: Install switch-trust-cli
          command: pip install switch-trust-cli
      
      - run:
          name: Install OpenGrep
          command: |
            curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash
            echo 'export PATH="$HOME/.opengrep/cli/latest:$PATH"' >> $BASH_ENV
      
      - run:
          name: Scan agent code
          command: switch-trust scan ./agent --output scan-results.json
          environment:
            GEMINI_API_KEY: ${GEMINI_API_KEY}
      
      - store_artifacts:
          path: scan-results.json
          destination: switch-trust-scan-results

workflows:
  validate:
    jobs:
      - scan

Access artifacts from the job’s Artifacts tab.CircleCI documentation →

Output formats

Switch Trust CLI writes results as JSON or as SARIF (Static Analysis Results Interchange Format), an open standard for reporting analysis findings.

Format	Extension	Use it for
`json`	`.json`	Build artifacts, dashboards, your own tooling
`sarif`	`.sarif`	Security tools that read SARIF, including GitHub code scanning

Tools that read SARIF ingest results from any SARIF-producing tool without a custom parser, so your findings land alongside the rest of your security results instead of in a file nobody opens. Switch Trust CLI writes SARIF 2.1.0.

Set the format

switch-trust scan and switch-trust eval run write JSON unless you ask for something else. Pass --format sarif (short form -f) to write SARIF instead. The output filename follows the format you choose:

Command	Default	With `--format sarif`
`switch-trust scan`	`scan_<timestamp>.json`	`scan_<timestamp>.sarif`
`switch-trust eval run`	`eval_<timestamp>.json`	`eval_<timestamp>.sarif`

What SARIF output contains

switch-trust scan
switch-trust eval run

Findings map to file locations with line numbers, and severity maps to SARIF levels: critical and high findings become error, medium becomes warning, and everything else becomes note.This is the output GitHub code scanning is built to read.Upload to GitHub code scanning:

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write   # required to upload SARIF
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

      - name: Install switch-trust-cli
        run: pip install switch-trust-cli

      - name: Install OpenGrep
        run: |
          curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash
          echo "$HOME/.opengrep/cli/latest" >> "$GITHUB_PATH"

      - name: Scan agent code
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: switch-trust scan ./agent --format sarif --output scan-results.sarif

      - name: Upload to code scanning
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: scan-results.sarif

Findings then appear in the Security tab of your repository and as annotations on the pull request, so reviewers see them without downloading an artifact.

Eval results identify the model that was tested rather than a file and line. That suits SARIF-aware tools generally, but tools built around source locations, such as GitHub code scanning, expect the file-and-line results that switch-trust scan produces.Reach for --format sarif here when your security tooling ingests SARIF and you want reliability scores in the same place as everything else. If your goal is annotations on a pull request, use switch-trust scan.

Exit codes

switch-trust scan and switch-trust eval run return the same exit codes, so a pipeline can tell a clean run from one that needs attention.

Code	Meaning	What to do
`0`	The run completed, and no gate was tripped	Proceed. Without a gate, check the results file for findings
`1`	An unexpected error	Read the log file the run wrote, `switch_trust_<timestamp>.log` unless you set `--log`
`2`	The command was used incorrectly, such as an unknown flag or an invalid `--fail-on` value	Check the command against Commands
`5`	A gate you set was tripped	Review the findings or scores in the results file
`6`	An evaluation run produced no result: nothing was scored, or it stopped before every evaluation ran	Read the message, which names the cause. It’s usually the agent endpoint or its credentials
`20`	An API key is missing or was rejected	Set the key in your CI secrets, or replace it. See API keys
`21`	A model provider accepted the API key but refused the call: the scanner model’s provider for a scan, or the model under test’s for an evaluation	Check that provider account’s plan, quota, or model access
`22`	The path you passed to `switch-trust scan` doesn’t exist, or an evaluation’s config or prompt file can’t be read	Check the path is relative to where the job runs, and that the code is checked out before the step runs
`23`	A scan found nothing it can analyze, or an evaluation run with `--fail-under` matched no evaluations	Point the scan at a folder with a `requirements.txt` or an agent built on a supported framework, or loosen your `--model-tag` and `--eval-tag` filters
`24`	An evaluation’s model endpoint returned not found (404)	Check the agent or model URL in your eval configuration
`25`	The configuration is invalid	Check your config file, `~/.switch-trust/config.json` unless you set `--config`. See Configuration
`26`	A scanner tool is missing: OpenGrep, Bandit, detect-secrets, or pip-audit when there are requirements files to audit	Install the tool the message names, and put it on `PATH`
`60`–`64`	A temporary failure: network, rate limit, timeout, or a server error	Retry the job. For a rate limit on `eval run`, lower `--concurrency`
`130`	Interrupted with Ctrl+C	—

The codes come in ranges a script can branch on: 20–39 need a fix before you rerun, and 60–79 are temporary, so a retry may succeed. For example:

switch-trust scan . --output results.json --fail-on high
ret=$?
if [ $ret -eq 0 ]; then
    echo "Security gate passed"
elif [ $ret -eq 5 ]; then
    echo "Security gate failed: findings at or above high"
elif [ $ret -ge 60 ] && [ $ret -lt 80 ]; then
    echo "Temporary failure: retry the scan"
else
    echo "The scan couldn't complete: check the log"
fi

Upgrading from 1.7: these runs used to exit 0, and now fail:

A scanner tool, such as OpenGrep, is missing: 26
A configured scanner model has no API key, or its key is rejected mid-scan: 20, or another configuration or retry code
An evaluation run scored nothing, including when every evaluation errored, or stopped before every evaluation ran: 6

Where a scan ran, it still writes its results first. A path that doesn’t exist now exits 22 instead of 1.

Fail the build on findings or scores

A completed run exits 0 unless you set a gate:

switch-trust scan --fail-on <severity>: Exits 5 if any finding is at or above critical, high, medium, low, or info, after triage. A finding whose severity can’t be read also trips it.
switch-trust eval run --fail-under <score>: Exits 5 if any evaluation scores below the value, from 0 to 1.

For example:

switch-trust scan . --output results.json --fail-on high

Both flags are off by default, and an invalid value exits 2 before anything runs. In CI, the CLI prints a warning when no gate is set. The CLI writes the results file before it checks the gate, so you can still save it as an artifact when the build fails. A missing scanner tool exits 26 even if findings would have tripped --fail-on.

Other CI systems

The core pattern works anywhere:

Provide Python 3.11 to 3.13

Switch Trust CLI requires Python 3.11 to 3.13 on a Linux or macOS runner. Use a prebuilt image where you can, such as python:3.11.

Install Switch Trust CLI

pip install switch-trust-cli

Install OpenGrep and put it on PATH

curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash

Add $HOME/.opengrep/cli/latest to PATH. This is the part that differs most between systems, because most of them run each step in a fresh shell: GitHub Actions writes the path to $GITHUB_PATH, CircleCI appends an export to $BASH_ENV, and GitLab CI runs the whole job in one shell, so a plain export carries. Find the equivalent on your system for persisting environment changes between steps.

Set your LLM API key

Store the key as a secret and expose it to the job as an environment variable: GEMINI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY.

Run the scan

switch-trust scan /path/to/agent --output results.json

Add --format sarif to write SARIF instead. See Output formats.

Save the results as a build artifact

Use your CI system’s artifact mechanism so the file outlives the job and reviewers can reach it from the pull request.

Overview

Switch Trust Scan

Switch Trust Eval

Guides

Reference

Troubleshooting

Resources

Output formats

Set the format

What SARIF output contains

Exit codes

Fail the build on findings or scores

Other CI systems