CI/CD Integration

Automate security scanning in your CI/CD pipeline so every commit and pull request is reviewed before merge.

Prerequisites

1. A CodeStax account on a Pro plan or higher
2. An API key (generate from Settings → API Keys)
3. At least one repository connected to CodeStax

GitHub Actions

Step 1: Add Your API Key as a Secret

1. Go to your GitHub repository → Settings → Secrets and variables → Actions
2. Click New repository secret
3. Name: CODESTAX_API_KEY
4. Value: your API key from CodeStax settings

Step 2: Create the Workflow File

Create .github/workflows/codestax.yml:

name: CodeStax Security Scan
on:
  pull_request:
    branches: [main, develop]
 
jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
 
      - name: Check out CodeStax CLI
        uses: actions/checkout@v4
        with:
          repository: codestax/codestax-platform
          path: codestax
 
      - name: Trigger PR review and enforce quality gate
        env:
          CODESTAX_API_KEY: ${{ secrets.CODESTAX_API_KEY }}
        run: python3 codestax/cli/main.py review ${{ vars.CODESTAX_REPO_ID }} ${{ github.event.pull_request.number }}
 
      - name: List recent reviews for this repository
        if: always()
        env:
          CODESTAX_API_KEY: ${{ secrets.CODESTAX_API_KEY }}
        run: python3 codestax/cli/main.py list --repo-id ${{ vars.CODESTAX_REPO_ID }} --limit 5

Step 3: Verify

Open a pull request. The workflow will run automatically and report results as a GitHub check.

GitLab CI

Step 1: Add Your API Key as a Variable

1. Go to your GitLab project → Settings → CI/CD → Variables
2. Add variable: CODESTAX_API_KEY with your API key
3. Check Mask variable to prevent exposure in logs

Step 2: Add to .gitlab-ci.yml

stages:
  - test
  - security
 
codestax-scan:
  stage: security
  image: python:3.11-alpine
  before_script:
    - git clone https://github.com/codestax/codestax-platform.git codestax
  script:
    - python3 codestax/cli/main.py review $CODESTAX_REPO_ID $CI_MERGE_REQUEST_IID
  variables:
    CODESTAX_API_KEY: $CODESTAX_API_KEY
  rules:
    - if: $CI_MERGE_REQUEST_IID
  allow_failure: false

Step 3: Verify

Create a merge request. The pipeline will include the security stage and block merge if the gate fails.

Configuration Options

All-in-One vs. Separate Steps

The review command is the recommended one-liner for CI: it triggers the PR review, waits for it to complete, and enforces the quality gate, exiting non-zero if the gate fails. If you need finer control, run the underlying steps separately:

# Trigger a review and wait for it to finish (prints the review ID)
python3 codestax/cli/main.py trigger <repo_id> <pr_number> --wait
 
# Enforce the quality gate against a completed review
python3 codestax/cli/main.py gate <review_id>

Immutable Quality-Gate Policy

The CLI cannot override quality-gate thresholds. The review worker evaluates the effective organization/repository policy and publishes one immutable, versioned gate snapshot. The CLI reads that same snapshot, so its result cannot diverge from the decision delivered to GitHub, GitLab, or Bitbucket.

Configure the organization policy under Settings → Policies. For a repository that needs stricter or more permissive limits, configure its repository policy override there. Policy changes apply to subsequently evaluated reviews; they do not rewrite a historical review’s captured decision.

# Uses the effective organization/repository policy captured by this review
python3 codestax/cli/main.py review $CODESTAX_REPO_ID $PR_NUMBER
 
# Reads the exact immutable decision already published for an existing review
python3 codestax/cli/main.py gate $REVIEW_ID

The gate can be passed, failed, or inconclusive. Incomplete, degraded, unverified, missing, or inconsistent evidence is inconclusive and must not be described as a policy failure or a pass. See the CLI exit-code contract for deterministic CI handling.

Repository and Branch Strategy

A common pattern is to assign stricter repository policy overrides to higher-risk repositories, then require the CodeStax provider signal on protected branches:

- name: PR Review
  if: github.event_name == 'pull_request'
  run: python3 codestax/cli/main.py review ${{ vars.CODESTAX_REPO_ID }} ${{ github.event.pull_request.number }}

Troubleshooting