CI/CD Integration

Unfault integrates with GitHub Actions, GitLab CI, and other CI/CD systems. All analysis runs locally. No credentials or external services are required for the core review.

Output Formats

Format	Flag	Use Case
basic	--output basic	Human-readable terminal output (default)
json	--output json	Machine-readable JSON for custom integrations
sarif	--output sarif	SARIF format for GitHub Code Scanning

Tip

Use --output sarif for seamless integration with GitHub’s security features, including inline annotations in pull requests and the Security tab.

GitHub Actions

Add this workflow to .github/workflows/unfault.yml:

name: Unfault

on:
  pull_request:
  push:
    branches: [main]

jobs:
  unfault:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Unfault
        run: |
          mkdir -p ~/.local/bin
          curl -L -o ~/.local/bin/unfault https://github.com/unfault/cli/releases/latest/download/unfault-x86_64-unknown-linux-gnu
          chmod +x ~/.local/bin/unfault
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Run Unfault review
        run: unfault review --output sarif --offline > results.sarif

      - name: Upload SARIF to GitHub
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Note --offline: this skips SLO/trace fetching, which requires observability credentials not typically present in CI. Remove it if you have those credentials configured.

CI Platforms

GitLab CI

Add to .gitlab-ci.yml:

unfault:
  image: debian:bookworm-slim
  stage: test
  before_script:
    - apt-get update && apt-get install -y curl
    - mkdir -p ~/.local/bin
    - curl -L -o ~/.local/bin/unfault https://github.com/unfault/cli/releases/latest/download/unfault-x86_64-unknown-linux-gnu
    - chmod +x ~/.local/bin/unfault
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - unfault review --output sarif --offline > gl-code-quality-report.json
  artifacts:
    reports:
      sast: gl-code-quality-report.json

Note

GitLab supports SARIF format for its SAST reports. Results appear in merge request security widgets.

CircleCI

Add to .circleci/config.yml:

version: 2.1

jobs:
  unfault:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run:
          name: Install Unfault
          command: |
            mkdir -p ~/.local/bin
            curl -L -o ~/.local/bin/unfault https://github.com/unfault/cli/releases/latest/download/unfault-x86_64-unknown-linux-gnu
            chmod +x ~/.local/bin/unfault
            echo 'export PATH="$HOME/.local/bin:$PATH"' >> $BASH_ENV
      - run:
          name: Run Unfault
          command: unfault review --output sarif --offline > results.sarif
      - store_artifacts:
          path: results.sarif

workflows:
  check:
    jobs:
      - unfault

Exit Codes

Code	Meaning	Action
0	Success, no findings	Proceed
1	General error	Check logs
2	Configuration error	Check config
4	Network error	Check connectivity
5	Findings detected	Review issues
6	Invalid input	Check arguments

Gate on Findings

To block a pipeline when findings are detected:

unfault review --offline
if [ $? -eq 5 ]; then
  echo "Findings detected. Run 'unfault review --output full' locally for details."
  exit 1
fi

Caching

Speed up CI runs by caching the Unfault binary:

- name: Cache Unfault
  uses: actions/cache@v4
  with:
    path: ~/.local/bin/unfault
    key: unfault-${{ runner.os }}-latest

- name: Install Unfault
  if: steps.cache.outputs.cache-hit != 'true'
  run: |
    mkdir -p ~/.local/bin
    curl -L -o ~/.local/bin/unfault https://github.com/unfault/cli/releases/latest/download/unfault-x86_64-unknown-linux-gnu
    chmod +x ~/.local/bin/unfault

With Observability Enrichment

If you want SLO/trace enrichment in CI, set the relevant credentials as secrets and drop --offline:

- name: Run Unfault review
  env:
    # GCP: configure GOOGLE_APPLICATION_CREDENTIALS or workload identity
    DD_API_KEY: ${{ secrets.DD_API_KEY }}
    DD_APP_KEY: ${{ secrets.DD_APP_KEY }}
  run: unfault review --output sarif > results.sarif

See SLO Discovery for details on observability integrations.