> ## Documentation Index
> Fetch the complete documentation index at: https://jonathansantilli-codegate-92.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD with GitHub Actions

> Run CodeGate in GitHub Actions to surface AI tool configuration risks in pull requests and block dangerous findings before merge.

CodeGate integrates with GitHub Actions through SARIF output and exit codes. Scanning in CI surfaces risks that live in repository-controlled files—MCP configs, hooks, workflows, rule markdown—before they reach production environments.

## Setting up the integration

<Steps>
  <Step title="Install CodeGate in your workflow">
    Add a step to install CodeGate globally before running the scan. Because CodeGate is published to npm, no additional authentication or registry configuration is required.

    ```yaml theme={null}
    - name: Install CodeGate
      run: npm install -g codegate-ai
    ```
  </Step>

  <Step title="Run the scan with --no-tui">
    Use `--no-tui` to disable the interactive terminal UI and interactive prompts. This flag is required in CI because there is no TTY and no user available to respond to prompts.

    ```yaml theme={null}
    - name: Run CodeGate
      run: codegate scan . --no-tui --format sarif --output codegate.sarif
    ```

    `--format sarif` produces a SARIF 2.1.0 report that GitHub Code Scanning can ingest directly. `--output` writes the report to a file instead of stdout.
  </Step>

  <Step title="Upload the SARIF report to GitHub Code Scanning">
    Use the `github/codeql-action/upload-sarif` action to publish findings to the Security tab of your repository. Findings appear as code scanning alerts and can be tracked over time.

    ```yaml theme={null}
    - name: Upload SARIF
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: codegate.sarif
    ```
  </Step>
</Steps>

## Complete workflow examples

<CodeGroup>
  ```yaml sarif-upload.yml theme={null}
  name: CodeGate Security Scan

  on:
    pull_request:
    push:
      branches:
        - main

  permissions:
    contents: read
    security-events: write

  jobs:
    codegate:
      name: CodeGate scan
      runs-on: ubuntu-latest
      steps:
        - name: Checkout
          uses: actions/checkout@v4

        - name: Install CodeGate
          run: npm install -g codegate-ai

        - name: Run CodeGate
          run: codegate scan . --no-tui --format sarif --output codegate.sarif

        - name: Upload SARIF
          uses: github/codeql-action/upload-sarif@v3
          with:
            sarif_file: codegate.sarif
  ```

  ```yaml workflow-audits.yml theme={null}
  name: CodeGate Workflow Audit

  on:
    pull_request:
    push:
      branches:
        - main

  permissions:
    contents: read
    security-events: write

  jobs:
    codegate:
      name: CodeGate workflow audit
      runs-on: ubuntu-latest
      steps:
        - name: Checkout
          uses: actions/checkout@v4

        - name: Install CodeGate
          run: npm install -g codegate-ai

        - name: Run CodeGate with workflow audits
          run: |
            codegate scan . \
              --no-tui \
              --workflow-audits \
              --collect project \
              --persona auditor \
              --format sarif \
              --output codegate.sarif

        - name: Upload SARIF
          uses: github/codeql-action/upload-sarif@v3
          with:
            sarif_file: codegate.sarif
  ```

  ```yaml fail-on-findings.yml theme={null}
  name: CodeGate Gate Check

  on:
    pull_request:

  permissions:
    contents: read

  jobs:
    codegate:
      name: CodeGate blocking check
      runs-on: ubuntu-latest
      steps:
        - name: Checkout
          uses: actions/checkout@v4

        - name: Install CodeGate
          run: npm install -g codegate-ai

        - name: Run CodeGate (fail on high+ findings)
          run: codegate scan . --no-tui --format json --output codegate.json
          # Exit code 2 means findings at or above severity_threshold.
          # Exit code 1 means findings exist but below threshold (non-blocking).
          # Exit code 0 means no unsuppressed findings.
  ```
</CodeGroup>

## Workflow audit integration

The `--workflow-audits` flag enables the CI/CD audit pack, which scans GitHub Actions workflows, action definitions, and Dependabot configuration for risks that a standard file scan does not cover.

```bash theme={null}
codegate scan . --workflow-audits --collect project --persona auditor --runtime-mode online
```

Workflow audit checks include:

* Unpinned external action references (`uses: owner/repo@tag` instead of a commit SHA)
* High-risk triggers (`pull_request_target`, `workflow_run`)
* Overly broad permissions (`write-all` and explicit write grants)
* Template expression injection patterns in `run` steps and known sink inputs
* Known vulnerable action references (requires `--runtime-mode online`)
* Dependabot cooldown and execution-risk checks
* Workflow hygiene issues such as missing concurrency gates, obfuscation, and unsafe conditional trust

Restrict the audit to specific artifact kinds with `--collect-kind`:

```bash theme={null}
# Audit only workflow files
codegate scan . --workflow-audits --collect-kind workflows

# Audit only Dependabot configuration
codegate scan . --workflow-audits --collect-kind dependabot
```

## Exit code handling in CI

CodeGate exits with a code that reflects the scan result. Use exit codes to decide whether a job should pass or fail.

| Exit code | Meaning                                               |
| --------- | ----------------------------------------------------- |
| `0`       | No unsuppressed findings                              |
| `1`       | Findings exist, all below `severity_threshold`        |
| `2`       | One or more findings at or above `severity_threshold` |
| `3`       | Scanner or runtime error                              |

Treat exit code `2` as a blocking condition. GitHub Actions stops the job when any step exits with a non-zero code, so a `codegate scan` step that exits `2` fails the job automatically.

To distinguish between "findings below threshold" (exit code `1`) and "findings at or above threshold" (exit code `2`) in shell logic:

```bash theme={null}
codegate scan . --no-tui --format json --output codegate.json
EXIT=$?

if [ $EXIT -eq 2 ]; then
  echo "Blocking findings detected. Review codegate.json before merging."
  exit 1
elif [ $EXIT -eq 1 ]; then
  echo "Non-blocking findings present. Review recommended."
  exit 0
elif [ $EXIT -eq 3 ]; then
  echo "Scanner error. Check the run log."
  exit 1
fi
```

See [Exit codes](/integrations/exit-codes) for the full reference.

## Using --format json for pipeline consumption

Use `--format json` when you want to process findings programmatically in your pipeline rather than uploading SARIF to GitHub Code Scanning.

```yaml theme={null}
- name: Run CodeGate (JSON output)
  run: codegate scan . --no-tui --format json --output codegate.json

- name: Parse findings count
  run: |
    FINDINGS=$(jq '.findings | length' codegate.json)
    echo "Total findings: $FINDINGS"
```

## Tips for CI environments

<Tip>
  Always pass `--no-tui` in CI. Without it, CodeGate may attempt to render an interactive terminal UI or pause for user input, which hangs the job.
</Tip>

<Tip>
  Use `--strict-collection` to treat workflow parse failures as high-severity findings. This prevents malformed workflow files from silently escaping audit coverage.
</Tip>

<Note>
  The `security-events: write` permission is required on the GitHub Actions job to upload SARIF results to Code Scanning. Without it, the upload step will fail.
</Note>

<Warning>
  Deep scan (`--deep`) is interactive by default and will hang in non-interactive CI environments unless `--force` is also provided. Avoid `--deep` in CI unless you have explicitly reviewed its behavior and accepted the additional exposure from remote metadata fetching.
</Warning>