Claude Code as a CI/CD Tool

Claude Code's headless mode (-p flag) transforms it from an interactive assistant into an automation tool. By running Claude Code in CI/CD pipelines, you can automate code reviews, generate changelogs, validate API contracts, check documentation, and enforce coding standards — all triggered by pull requests.

This guide covers practical CI/CD integrations using GitHub Actions, though the patterns apply to any CI system (GitLab CI, CircleCI, Jenkins).

GitHub Actions Integration

Basic PR Review Action

# .github/workflows/claude-review.yml
name: Claude Code PR Review

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for diff

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          REVIEW=$(echo "$DIFF" | claude -p "Review this pull request diff. Report:
          1. Bugs and logic errors
          2. Security vulnerabilities
          3. Performance concerns
          4. Missing error handling
          5. Breaking API changes

          Format as markdown with severity labels: [CRITICAL], [WARNING], [INFO].
          If no issues found, respond with 'No issues found.'" --output-format text 2>/dev/null)

          # Post as PR comment
          gh pr comment ${{ github.event.pull_request.number }} --body "$REVIEW"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Targeted File Review

Review only specific file types or directories:

      - name: Review API Changes
        if: contains(github.event.pull_request.labels.*.name, 'api-change')
        run: |
          API_DIFF=$(git diff origin/main...HEAD -- 'src/api/**' 'src/schemas/**')
          if [ -n "$API_DIFF" ]; then
            REVIEW=$(echo "$API_DIFF" | claude -p "Review these API changes for:
            1. Breaking changes to existing endpoints
            2. Missing input validation
            3. Incorrect HTTP status codes
            4. Response schema inconsistencies
            5. Missing pagination on list endpoints" --output-format text 2>/dev/null)
            gh pr comment ${{ github.event.pull_request.number }} --body "## API Review
$REVIEW"
          fi

Automated Changelog Generation

# .github/workflows/changelog.yml
name: Generate Changelog

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate Changelog Entry
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          COMMITS=$(git log origin/main...HEAD --oneline --no-merges)
          DIFF_STAT=$(git diff --stat origin/main...HEAD)

          CHANGELOG=$(claude -p "Based on these commits and changes, generate a changelog entry.

          Commits:
          $COMMITS

          Files changed:
          $DIFF_STAT

          Format the changelog as:
          ### Added
          - [feature descriptions]

          ### Changed
          - [change descriptions]

          ### Fixed
          - [bug fix descriptions]

          Only include relevant sections. Be concise — one line per item." --output-format text 2>/dev/null)

          gh pr comment ${{ github.event.pull_request.number }} --body "## Suggested Changelog
$CHANGELOG"

Migration Safety Check

# .github/workflows/migration-check.yml
name: Migration Safety Check

on:
  pull_request:
    paths:
      - 'prisma/migrations/**'
      - 'alembic/versions/**'

jobs:
  check-migration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Review Migration Safety
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          MIGRATION_FILES=$(git diff --name-only origin/main...HEAD -- 'prisma/migrations/**' 'alembic/versions/**')

          for file in $MIGRATION_FILES; do
            if [ -f "$file" ]; then
              CONTENT=$(cat "$file")
              REVIEW=$(echo "$CONTENT" | claude -p "Review this database migration for safety:

              1. Does it drop any columns or tables? (CRITICAL if yes)
              2. Does it add NOT NULL columns without defaults? (CRITICAL — will fail on existing data)
              3. Does it rename columns? (WARNING — may break running code)
              4. Does it add indexes on large tables? (WARNING — may lock table)
              5. Is there a rollback path?

              Rate overall risk: LOW, MEDIUM, HIGH, or CRITICAL." --output-format text 2>/dev/null)

              gh pr comment ${{ github.event.pull_request.number }} --body "## Migration Review: `$file`
$REVIEW"
            fi
          done

Documentation Verification

      - name: Check Documentation
        run: |
          DIFF=$(git diff origin/main...HEAD)
          DOC_CHECK=$(echo "$DIFF" | claude -p "Analyze this diff and determine if documentation needs updating:

          1. Were any public API endpoints added or modified?
          2. Were any environment variables added?
          3. Were any configuration files changed?
          4. Were any breaking changes introduced?

          For each 'yes', specify what documentation should be updated.
          If no documentation changes needed, respond with 'Documentation is up to date.'" --output-format text 2>/dev/null)

          if ! echo "$DOC_CHECK" | grep -q "up to date"; then
            gh pr comment ${{ github.event.pull_request.number }} --body "## Documentation Check
$DOC_CHECK"
            gh pr edit ${{ github.event.pull_request.number }} --add-label "needs-docs"
          fi

Cost Management in CI

Claude Code API calls in CI can add up. Here are strategies to control costs:

1. Run Only on Meaningful Changes

on:
  pull_request:
    paths:
      - 'src/**'
      - 'lib/**'
      - '!**/*.md'
      - '!**/*.txt'

2. Use Sonnet for CI Reviews

Sonnet is cheaper than Opus and sufficient for most review tasks:

claude -p "Review this diff" --model sonnet --max-turns 5

3. Limit Diff Size

DIFF=$(git diff origin/main...HEAD)
DIFF_SIZE=$(echo "$DIFF" | wc -c)

if [ "$DIFF_SIZE" -gt 100000 ]; then
  echo "Diff too large for AI review ($DIFF_SIZE bytes). Skipping."
  exit 0
fi

4. Cache Reviews

      - name: Check Cache
        id: cache
        run: |
          DIFF_HASH=$(git diff origin/main...HEAD | sha256sum | cut -d' ' -f1)
          echo "hash=$DIFF_HASH" >> $GITHUB_OUTPUT

      - uses: actions/cache@v4
        id: review-cache
        with:
          path: .review-cache
          key: claude-review-${{ steps.cache.outputs.hash }}

      - name: Run Review
        if: steps.review-cache.outputs.cache-hit != 'true'
        run: |
          # ... review logic ...

Multi-Stage Review Pipeline

For large projects, split the review into specialized stages:

jobs:
  security-review:
    runs-on: ubuntu-latest
    steps:
      - name: Security Review
        run: |
          git diff origin/main...HEAD | claude -p "Security-only review. Check for: injection, XSS, auth bypass, data exposure, SSRF. Only report security issues." --model sonnet

  performance-review:
    runs-on: ubuntu-latest
    steps:
      - name: Performance Review
        run: |
          git diff origin/main...HEAD -- '*.py' '*.ts' | claude -p "Performance-only review. Check for: N+1 queries, missing indexes, unbounded queries, memory leaks, missing pagination." --model sonnet

  api-review:
    runs-on: ubuntu-latest
    if: contains(github.event.pull_request.labels.*.name, 'api-change')
    steps:
      - name: API Contract Review
        run: |
          git diff origin/main...HEAD -- 'src/api/**' | claude -p "Check for breaking API changes, inconsistent response formats, missing validation." --model sonnet

GitLab CI Equivalent

# .gitlab-ci.yml
claude-review:
  stage: review
  image: node:20
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - DIFF=$(git diff origin/main...HEAD)
    - REVIEW=$(echo "$DIFF" | claude -p "Review this MR for bugs, security issues, and performance problems." --output-format text 2>/dev/null)
    - |
      curl --request POST "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"         --header "PRIVATE-TOKEN: $GITLAB_TOKEN"         --data-urlencode "body=$REVIEW"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

Measuring CI Review Effectiveness

Track these metrics to evaluate your Claude Code CI integration:

Issues caught — How many review comments led to code changes?
False positive rate — How many comments were dismissed as irrelevant?
Time to first review — AI reviews arrive in 1-3 minutes vs hours for human reviewers
Cost per review — Track API spend per PR
Bug escape rate — Are fewer bugs reaching production?

Conclusion

Integrating Claude Code into CI/CD pipelines automates the tedious parts of code review — checking for common bugs, security issues, and performance problems — on every pull request. The key is treating AI reviews as a complement to human reviews, not a replacement. Use headless mode for automation, Sonnet for cost efficiency, and targeted review prompts for specific concerns. The result is faster review cycles, more consistent quality, and human reviewers who can focus on architecture and design.

Claude Code in CI/CD: Automating Pull Request Review Pipelines