How to Integrate Strix with GitHub Actions for CI/CD Security Scanning

Strix integrates with GitHub Actions by running in non-interactive mode (-n/--non-interactive), which streams findings to stdout and exits with code 2 if vulnerabilities are detected, automatically blocking pull requests that fail security checks.

Strix is a CLI-first security-testing platform from the usestrix/strix repository that runs completely headless, making it ideal for CI/CD pipelines. By leveraging its deterministic exit codes and Docker-based execution, you can integrate Strix into GitHub Actions to scan every pull request for vulnerabilities before code reaches production.

How Strix Headless Mode Works for CI/CD

Understanding Strix's headless execution model is essential for configuring robust security gates in your pipeline.

Entry Point and Argument Parsing

The integration starts at strix/interface/main.py, where the main() function parses command-line arguments including --non-interactive, --scan-mode, and --target【/cache/repos/github.com/usestrix/strix/main/strix/interface/main.py#L21-L30】. When args.non_interactive evaluates to true, Strix bypasses the TUI and invokes run_cli(args) to execute a headless scan【/cache/repos/github.com/usestrix/strix/main/strix/interface/main.py#L57-L60】.

Docker Image Handling

Strix executes scans inside a Docker container to ensure reproducible environments. During initialization, the main() function calls pull_docker_image() to cache the required image locally【/cache/repos/github.com/usestrix/strix/main/strix/interface/main.py#L26-L28】. This guarantees that every CI run uses the same scanning environment regardless of the GitHub Actions runner state.

Exit Code Behavior

Strix returns specific exit codes that GitHub Actions interprets as step status:

• 0 — No vulnerabilities found; workflow continues.
• 2 — Vulnerabilities detected; GitHub Actions treats this as a failure and blocks the PR.
• 1 — Execution error (e.g., missing Docker or malformed arguments); workflow fails.

The runner automatically halts the pipeline on any non-zero status, making Strix a drop-in security gate.

Setting Up the GitHub Actions Workflow

Create .github/workflows/security.yml to run Strix on every pull request. The workflow installs Strix via the official installer, configures LLM secrets, and executes a fast scan.

name: Security Scan

on:
  pull_request:

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

      - name: Install Strix
        run: curl -sSL https://strix.ai/install | bash

      - name: Run Strix Scan
        env:
          STRIX_LLM: ${{ secrets.STRIX_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: strix -n -t ./ --scan-mode quick

Source: This pattern is documented in docs/integrations/github-actions.mdx【/cache/repos/github.com/usestrix/strix/main/docs/integrations/github-actions.mdx#L10-L30】 and matches the CI configuration shown in the project README【/cache/repos/github.com/usestrix/strix/main/README.md#L86-L110】.

Configuring Scan Modes and Environment Variables

Tailor Strix's behavior to your repository's risk profile and PR velocity by adjusting scan depth and LLM configuration.

Selecting the Right Scan Mode

Strix offers three scan modes controlled via --scan-mode:

• quick — Fastest option for PR validation; scans surface-level vulnerabilities.
• standard — Balanced depth for regular CI runs.
• deep — Comprehensive analysis for nightly builds or pre-release validation.

Refer to docs/usage/scan-modes.mdx for timing expectations and trade-offs【/cache/repos/github.com/usestrix/strix/main/docs/usage/scan-modes.mdx#L8-L58】. For example, use deep mode in scheduled workflows:

name: Nightly Security Scan
on:
  schedule:
    - cron: '0 0 * * *'

jobs:
  deep-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -sSL https://strix.ai/install | bash
      - env:
          STRIX_LLM: ${{ secrets.STRIX_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: strix -n -t ./ --scan-mode deep

Required Secrets and LLM Configuration

Strix requires two environment variables stored in your repository's GitHub Secrets:

1. STRIX_LLM — The LLM model identifier (e.g., openai/gpt-4, ollama/phi).
2. LLM_API_KEY — Authentication key for the LLM provider.

For self-hosted LLMs, additionally set LLM_API_BASE to point to your custom endpoint. These variables are read directly by the CLI at startup according to the secrets table in the official documentation【/cache/repos/github.com/usestrix/strix/main/docs/integrations/github-actions.mdx#L32-L39】.

Capturing Scan Artifacts

Strix writes detailed reports to strix_runs/<run-name>/ on the filesystem. Persist these artifacts for security review and compliance auditing by adding an upload step that runs regardless of scan results:

      - name: Upload Scan Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: strix-report
          path: strix_runs/

This ensures that even when Strix exits with code 2 (vulnerabilities found), the security team can download the full analysis from the Actions workflow summary.

Summary

• Strix runs headlessly using the -n/--non-interactive flag in strix/interface/main.py, invoking run_cli() instead of the interactive TUI.
• Exit code 2 triggers GitHub Actions to fail the workflow, blocking vulnerable PRs from merging.
• Install via curl using the official strix.ai/install script, which configures the binary and Docker image.
• Configure secrets for STRIX_LLM and LLM_API_KEY to enable AI-driven vulnerability detection.
• Choose scan modes (quick, standard, deep) based on pipeline timing requirements documented in docs/usage/scan-modes.mdx.
• Archive reports from the strix_runs/ directory using actions/upload-artifact for audit trails.

Frequently Asked Questions

What exit codes does Strix return in CI/CD pipelines?

Strix returns three specific exit codes as implemented in strix/interface/main.py: 0 indicates no vulnerabilities were found, 2 indicates vulnerabilities were detected (causing GitHub Actions to fail the step), and 1 indicates an execution error such as missing Docker or invalid arguments.

How do I configure Strix to use a self-hosted LLM in GitHub Actions?

Set the STRIX_LLM environment variable to your model identifier (e.g., ollama/phi) and optionally specify LLM_API_BASE to point to your local endpoint. Store these values in your repository's GitHub Secrets and reference them in the workflow environment block, just as you would with cloud-based LLM credentials.

Where are scan reports stored in the GitHub Actions runner?

Strix writes its output to the strix_runs/<run-name>/ directory within the working directory of the runner. You can persist these files using actions/upload-artifact with if: always() to ensure reports are available for download even when the scan detects vulnerabilities and exits with code 2.

Can I run Strix on every commit instead of just pull requests?

Yes. Modify the on: trigger in your workflow file from pull_request to push or include both triggers. You can also create separate workflows for different events—such as quick scans on PRs and deep scans on scheduled nightly runs—to balance security coverage with CI execution time.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}