CI/CD Integration

Unfault integrates with GitHub Actions, GitLab CI, and other CI/CD systems to catch issues before they reach production.

Output Formats

The unfault review command supports multiple output formats:

Format	Flag	Use Case
text	--output=text	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: curl -sSL https://unfault.dev/get | bash

      - name: Run Unfault review
        env:
          UNFAULT_API_KEY: ${{ secrets.UNFAULT_API_KEY }}
        run: unfault review --output sarif > results.sarif

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

This configuration:

1. Runs on every pull request and push to main
2. Uploads SARIF results to GitHub’s Security tab
3. Shows findings inline in pull request diffs with full context

Getting an API Key

1. Go to your Unfault dashboard
2. Navigate to Settings > API Keys
3. Create a new key with appropriate permissions
4. Add it to your repository secrets as UNFAULT_API_KEY

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
    - curl -sSL https://unfault.dev/get | bash
  script:
    - unfault review --output sarif > gl-code-quality-report.json
  artifacts:
    reports:
      sast: gl-code-quality-report.json
  variables:
    UNFAULT_API_KEY: $UNFAULT_API_KEY

Note

GitLab supports SARIF format for its SAST reports. Results will 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: curl -sSL https://unfault.dev/get | bash
      - run:
          name: Run Unfault
          command: unfault review --output sarif > results.sarif
      - store_artifacts:
          path: results.sarif

workflows:
  check:
    jobs:
      - unfault

Exit Codes

The CLI uses standard exit codes for CI/CD integration:

Code	Meaning	Action
0	Success, no issues	✅ Proceed
1	General error	🔍 Check logs
2	Configuration error	Run unfault login
3	Authentication failed	Re-authenticate
4	Network error	Check connectivity
5	Findings detected	🚨 Review issues
6	Invalid input	Check arguments
7	Service unavailable	Retry later
8	Session error	Retry analysis
10	Subscription required	Upgrade plan

Pull Request Comments

Caution

When using SARIF upload (recommended), GitHub automatically shows findings as annotations in pull requests. The manual approach below is only needed for custom comment formatting.

For custom PR comments with JSON output:

- name: Run Unfault review
  id: unfault
  run: |
    unfault review --output json > results.json
    echo "findings=$(cat results.json | jq '.findings | length')" >> $GITHUB_OUTPUT

- name: Comment on PR
  if: ${{ steps.unfault.outputs.findings > 0 }}
  uses: actions/github-script@v7
  with:
    script: |
      const results = require('./results.json');
      const body = `## Unfault found ${results.findings.length} findings\n\n` +
        results.findings.map(f => `- **${f.rule}**: ${f.message}`).join('\n');
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body
      });

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 }}

- name: Install Unfault
  if: steps.cache.outputs.cache-hit != 'true'
  run: curl -sSL https://unfault.dev/get | bash

Environment Variables

Variable	Purpose
UNFAULT_API_KEY	Authentication for CI
UNFAULT_NO_COLOR	Disable colored output
UNFAULT_DEBUG	Enable debug logging