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

> Integrate Strix with GitHub Actions for CI/CD security scanning. Automatically block pull requests with vulnerabilities by running Strix in non-interactive mode. Enhance your workflow security now.

- Repository: [Strix/strix](https://github.com/usestrix/strix)
- Tags: how-to-guide
- Published: 2026-03-26

---

**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`](https://github.com/usestrix/strix/blob/main/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`](https://github.com/usestrix/strix/blob/main/.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.

```yaml
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:

```yaml
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:

```yaml
      - 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`](https://github.com/usestrix/strix/blob/main/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`](https://github.com/usestrix/strix/blob/main/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.