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

1. 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.

   - name: Install CodeGate
     run: npm install -g codegate-ai
   
2. 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.

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

3. 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.

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

Complete workflow examples

sarif-upload.yml

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

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.

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:

# 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:

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

- 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

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.

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

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.

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.