Skip to Content
FeaturesCI/CD Integration

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]
  push:
    branches: [main]
 
jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Install CodeStax CLI
        run: npm install -g @codestax/cli
 
      - name: Run Security Scan
        env:
          CODESTAX_API_KEY: ${{ secrets.CODESTAX_API_KEY }}
        run: codestax trigger --repo ${{ github.repository }} --type smart --wait
 
      - name: Enforce Quality Gate
        env:
          CODESTAX_API_KEY: ${{ secrets.CODESTAX_API_KEY }}
        run: codestax gate --repo ${{ github.repository }} --max-critical 0 --max-high 5
 
      - name: Upload SARIF Results
        if: always()
        env:
          CODESTAX_API_KEY: ${{ secrets.CODESTAX_API_KEY }}
        run: |
          codestax export --repo ${{ github.repository }} --format sarif --output results.sarif
 
      - name: Upload to GitHub Security
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

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: node:20-alpine
  before_script:
    - npm install -g @codestax/cli
  script:
    - codestax trigger --repo $CI_PROJECT_PATH --type smart --wait
    - codestax gate --repo $CI_PROJECT_PATH --max-critical 0 --max-high 5
  variables:
    CODESTAX_API_KEY: $CODESTAX_API_KEY
  rules:
    - if: $CI_MERGE_REQUEST_IID
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  artifacts:
    when: always
    reports:
      sast: codestax-results.json
    paths:
      - codestax-results.json
  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

Scan Types in CI

TypeDurationCoverageRecommended For
smart1-3 minSAST + SecretsPull requests
deep5-15 minAll scannersMain branch pushes

Quality Gate Thresholds

Customize the gate to match your team’s risk tolerance:

# Strict — block on any high or critical
codestax gate --max-critical 0 --max-high 0
 
# Moderate — allow some high findings
codestax gate --max-critical 0 --max-high 5
 
# Score-based — block above a risk score
codestax gate --max-score 50

Branch Strategy

A common pattern is to use different scan configurations per branch:

# PR branches: fast smart scan
- name: PR Scan
  if: github.event_name == 'pull_request'
  run: codestax trigger --type smart --wait
 
# Main branch: thorough deep scan
- name: Release Scan
  if: github.ref == 'refs/heads/main'
  run: codestax trigger --type deep --wait

Troubleshooting

IssueSolution
Authentication error (exit code 2)Verify CODESTAX_API_KEY is set correctly in secrets
Repository not foundEnsure the repo is connected in CodeStax dashboard
Scan timeoutIncrease the --wait timeout or use async mode
Gate fails unexpectedlyRun codestax issues to see which findings triggered the failure
CLI ReferenceCustom Rules