[20260312_DOCS] Added stable anchors used by the current website's guide links.

DevOps & CI/CD Integration¶

Automate code analysis and security scanning in your development workflow.

Overview¶

Code Scalpel integrates into:

Pre-commit hooks - Scan before commits
Pull request checks - Analyze on every PR
CI pipelines - Automated testing and security
Release gates - Block releases with vulnerabilities

GitHub Actions¶

Basic Security Scan¶

# .github/workflows/security.yml
name: Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Code Scalpel
        run: pip install code-scalpel

      - name: Run Security Scan
        run: |
          code-scalpel scan --security ./src --output json > security-report.json

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: security-report
          path: security-report.json

      - name: Check for Critical Issues
        run: |
          CRITICAL=$(jq '.summary.critical' security-report.json)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "::error::Found $CRITICAL critical vulnerabilities"
            exit 1
          fi

Full Analysis Pipeline¶

# .github/workflows/code-analysis.yml
name: Code Analysis

on:
  pull_request:
    branches: [main, develop]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Code Scalpel
        run: pip install codescalpel

      - name: Configure License
        env:
          CODE_SCALPEL_LICENSE: ${{ secrets.CODE_SCALPEL_LICENSE }}
        run: |
          echo "$CODE_SCALPEL_LICENSE" > /tmp/license.jwt
          export CODE_SCALPEL_LICENSE_PATH=/tmp/license.jwt

      - name: Analyze Project Structure
        run: code-scalpel analyze --project-map ./src

      - name: Check Complexity
        run: |
          code-scalpel analyze --complexity ./src --threshold 15

      - name: Security Scan
        run: |
          code-scalpel scan --security ./src --cross-file

      - name: Dependency Scan
        run: |
          code-scalpel scan --dependencies requirements.txt

PR Comment with Results¶

      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = JSON.parse(fs.readFileSync('security-report.json'));

            let body = '## Security Scan Results\n\n';
            body += `| Severity | Count |\n|----------|-------|\n`;
            body += `| Critical | ${report.summary.critical} |\n`;
            body += `| High | ${report.summary.high} |\n`;
            body += `| Medium | ${report.summary.medium} |\n`;

            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: body
            });

GitLab CI¶

# .gitlab-ci.yml
stages:
  - analyze
  - security
  - deploy

analyze:
  stage: analyze
  image: python:3.11
  script:
    - pip install codescalpel
    - code-scalpel analyze --project-map ./src
    - code-scalpel analyze --complexity ./src --output complexity.json
  artifacts:
    reports:
      codequality: complexity.json

security:
  stage: security
  image: python:3.11
  script:
    - pip install codescalpel
    - code-scalpel scan --security ./src --output gl-sast-report.json
  artifacts:
    reports:
      sast: gl-sast-report.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Pre-commit Hooks¶

Setup¶

pip install pre-commit

Configuration¶

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: code-scalpel-security
        name: Code Scalpel Security Scan
        entry: code-scalpel scan --security
        language: system
        types: [python]
        pass_filenames: false

      - id: code-scalpel-complexity
        name: Code Scalpel Complexity Check
        entry: code-scalpel analyze --complexity --threshold 15
        language: system
        types: [python]
        pass_filenames: true

Install Hooks¶

pre-commit install

Docker Integration¶

Docker Compose¶

# docker-compose.yml
version: '3.8'

services:
  code-scalpel:
    image: ghcr.io/codescalpel/code-scalpel
    volumes:
      - ./src:/workspace/src:ro
      - ./reports:/workspace/reports
      - ${CODE_SCALPEL_LICENSE_PATH:-/dev/null}:/license.jwt:ro
    environment:
      - CODE_SCALPEL_LICENSE_PATH=/license.jwt
    command: scan --security /workspace/src --output /workspace/reports/security.json

  app:
    build: .
    depends_on:
      code-scalpel:
        condition: service_completed_successfully

Multi-stage Build with Scanning¶

# Dockerfile
FROM python:3.11 as scanner
WORKDIR /app
RUN pip install codescalpel
COPY src/ ./src/
RUN code-scalpel scan --security ./src --exit-on-critical

FROM python:3.11-slim as runtime
WORKDIR /app
COPY --from=scanner /app/src ./src
COPY requirements.txt .
RUN pip install -r requirements.txt
CMD ["python", "-m", "src.main"]

Security Gates¶

Block on Critical Vulnerabilities¶

# GitHub Actions
- name: Security Gate
  run: |
    result=$(code-scalpel scan --security ./src --json)
    critical=$(echo $result | jq '.summary.critical')
    high=$(echo $result | jq '.summary.high')

    if [ "$critical" -gt 0 ]; then
      echo "::error::BLOCKED: $critical critical vulnerabilities found"
      exit 1
    fi

    if [ "$high" -gt 5 ]; then
      echo "::error::BLOCKED: $high high severity issues (threshold: 5)"
      exit 1
    fi

    echo "::notice::Security gate passed"

Configurable Thresholds¶

# .code-scalpel/gates.yaml
security_gate:
  block_on:
    critical: 1   # Block if any critical
    high: 5       # Block if more than 5 high
  warn_on:
    medium: 10    # Warn if more than 10 medium

code-scalpel gate --config .code-scalpel/gates.yaml

Scheduled Scans¶

Daily Security Scan¶

# .github/workflows/scheduled-scan.yml
name: Scheduled Security Scan

on:
  schedule:
    - cron: '0 2 * * *'  # 2 AM daily

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Code Scalpel
        run: pip install code-scalpel

      - name: Full Security Scan
        run: |
          code-scalpel scan --security . --cross-file --output full-report.json

      - name: Check for New Issues
        run: |
          # Compare with previous scan
          code-scalpel diff --baseline previous-report.json --current full-report.json

      - name: Alert on New Vulnerabilities
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: 'New vulnerabilities detected',
              body: 'Scheduled security scan found new issues.',
              labels: ['security', 'automated']
            });

Environment Variables¶

Variable	Description
`CODE_SCALPEL_LICENSE_PATH`	Path to license file
`CODE_SCALPEL_CONFIG_DIR`	Custom config directory
`CODE_SCALPEL_LOG_LEVEL`	Logging verbosity
`CODE_SCALPEL_OUTPUT_FORMAT`	Default output format

GitHub Secrets Setup¶

# Store license as secret
gh secret set CODE_SCALPEL_LICENSE < license.jwt

Best Practices¶

1. Fail Fast¶

Put security scans early in your pipeline:

stages:
  - security   # First
  - lint
  - test
  - build
  - deploy

2. Cache Dependencies¶

- name: Cache Code Scalpel
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-code-scalpel

3. Incremental Scanning¶

Only scan changed files on PRs:

- name: Get Changed Files
  id: files
  uses: tj-actions/changed-files@v41
  with:
    files: |
      **/*.py

- name: Scan Changed Files
  if: steps.files.outputs.any_changed == 'true'
  run: |
    code-scalpel scan --security ${{ steps.files.outputs.all_changed_files }}

4. Report Artifacts¶

Always save reports for audit:

- name: Upload Reports
  uses: actions/upload-artifact@v4
  with:
    name: code-scalpel-reports
    path: |
      security-report.json
      complexity-report.json
    retention-days: 90

Next Steps¶

Security Guide - Deep dive into security scanning
Enterprise Guide - Organization-wide deployment
Configuration - Configure Code Scalpel