Claude Code10 min read

Claude Code + GitHub Actions: Complete CI/CD Integration Guide

Learn how to integrate Claude Code into GitHub Actions for automated code review, PR fixes, and intelligent CI/CD pipelines. Step-by-step tutorial with YAML examples.

Claude Code + GitHub Actions: Complete CI/CD Integration Guide

Every pull request review cycle costs time. Senior engineers context-switch, junior developers wait hours for feedback, and subtle bugs slip through on Friday afternoons. Claude Code can change that — running as a fully autonomous agent inside your GitHub Actions pipeline, reviewing code, fixing failing tests, and posting inline comments before a human reviewer ever opens the tab.

This guide walks through the complete setup: headless mode fundamentals, the official claude-code-action, CLAUDE.md configuration for consistent behavior, and practical workflow patterns you can drop into any repository today.

What Is Claude Code Headless Mode (and Why It Matters for CI)?

When you run Claude Code in your terminal, it operates interactively — prompting you, waiting for confirmation, streaming output. Headless mode flips that model: you pass a prompt via the -p flag, Claude runs its full agent loop (thinking, tool calls, file edits), then exits with a structured result.

bash# Headless mode — runs once, exits, returns output
claude -p "Review the diff in this PR for security vulnerabilities and post findings"

This makes Claude Code composable with any CI system. GitHub Actions, GitLab CI, CircleCI, Jenkins — if it can run a shell command, it can run Claude in headless mode.

The implications are significant:

  • No human in the loop required — Claude reads your codebase, understands context, makes decisions
  • Consistent behavior — same review standards on every PR, not just when a senior engineer has time
  • Fast feedback loops — review results appear in minutes, not hours
  • Scales linearly — 10 PRs open simultaneously? Claude handles all 10 in parallel

The key constraint: headless mode runs best with a well-defined prompt and a CLAUDE.md that sets the rules. Without those, you get inconsistent output.

Setting Up the Official claude-code-action

Anthropic ships a first-party GitHub Action — anthropics/claude-code-action — that handles authentication, rate limiting, and output formatting out of the box. Here's the minimal setup:

Prerequisites

  • An Anthropic API key with billing enabled
  • Add the key to your repo's GitHub Secrets as ANTHROPIC_API_KEY
  • A CLAUDE.md at your repo root (covered in the next section)
  • Basic PR Review Workflow

    Create .github/workflows/claude-review.yml:

    yamlname: Claude Code Review
    
    on:
      pull_request:
        types: [opened, synchronize, reopened]
    
    permissions:
      contents: read
      pull-requests: write
    
    jobs:
      claude-review:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v4
            with:
              fetch-depth: 0  # Full history needed for diff analysis
    
          - name: Claude Code Review
            uses: anthropics/claude-code-action@v1
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              prompt: |
                Review this pull request and post inline comments for:
                1. Logic errors and edge cases
                2. Security vulnerabilities (SQL injection, XSS, auth bypasses)
                3. Performance issues (N+1 queries, blocking calls, memory leaks)
                4. Missing error handling
                Focus on the changed files only. Be specific — cite line numbers.

    This triggers on every PR open or update, runs Claude against the diff, and posts findings as inline review comments. Reviewers see Claude's analysis before they start reading.

    Auto-Fix Failing CI Tests

    A more powerful pattern: when CI tests fail, have Claude attempt an automatic fix.

    yamlname: Auto-Fix Failing Tests
    
    on:
      workflow_run:
        workflows: ["Run Tests"]
        types: [completed]
    
    jobs:
      auto-fix:
        if: ${{ github.event.workflow_run.conclusion == 'failure' }}
        runs-on: ubuntu-latest
        permissions:
          contents: write
          pull-requests: write
    
        steps:
          - name: Checkout
            uses: actions/checkout@v4
            with:
              ref: ${{ github.event.workflow_run.head_branch }}
    
          - name: Setup Node.js
            uses: actions/setup-node@v4
            with:
              node-version: '20'
    
          - name: Install dependencies
            run: npm ci
    
          - name: Run tests and capture output
            id: test-run
            run: npm test 2>&1 | tee test-output.txt || true
    
          - name: Claude Auto-Fix
            uses: anthropics/claude-code-action@v1
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              prompt: |
                The following tests are failing:
                
                $(cat test-output.txt)
                
                Diagnose the root cause by reading the relevant source files, 
                then fix the code (not the tests). Commit your changes with 
                a descriptive message explaining what broke and why.

    Claude reads the failure output, traces it back to the source, edits the files, and commits a fix — all without human intervention. You review the auto-fix commit, not the broken code.

    Configuring CLAUDE.md for Consistent CI Behavior

    CLAUDE.md is the persistent configuration file Claude Code reads at the start of every session — interactive or headless. In a CI context, it's how you enforce consistent standards across all automated reviews.

    Create CLAUDE.md at your repo root:

    markdown# Project: YourApp API
    
    ## Code Review Standards
    
    When reviewing pull requests, apply these standards:
    
    ### Security (P0 — always flag)
    - SQL queries must use parameterized statements, never string interpolation
    - User input must be sanitized before rendering in HTML contexts  
    - API endpoints must verify authentication before returning data
    - Secrets must never appear in code, logs, or error messages
    
    ### Performance (P1 — flag if clearly problematic)
    - Database queries inside loops are a blocking issue
    - Synchronous operations in async contexts should use proper await patterns
    - Heavy computations should be offloaded to background workers
    
    ### Style (P2 — suggest, don't block)
    - Follow the patterns in src/utils/ for new utility functions
    - Prefer early returns over deeply nested conditionals
    - TypeScript types should be explicit, avoid `any`
    
    ## Repository Structure
    
    - `src/api/` — Express route handlers (thin controllers only)
    - `src/services/` — Business logic (all DB calls live here)
    - `src/models/` — Prisma schema and model types
    - `tests/` — Jest test files mirror src/ structure
    
    ## What NOT to Flag
    
    - Minor style differences that don't affect readability
    - Test file formatting (we're relaxed there)
    - Comments in languages other than English (international team)
    
    ## Auto-Fix Permission
    
    When running in CI auto-fix mode, you MAY:
    - Edit source files to fix broken tests
    - Add missing error handling
    - Fix type errors
    
    You MUST NOT:
    - Modify test files
    - Change database schema files without explicit instruction
    - Delete files

    This file serves as both a prompt and a policy document. Claude reads it in every CI run, so your review standards are version-controlled alongside your code.

    Advanced Patterns: Specialized Review Agents

    For larger repositories, a single review prompt does everything moderately well. Specialized agents do specific things excellently. Here's a multi-job pattern that runs focused agents in parallel:

    yamlname: Specialized Code Review
    
    on:
      pull_request:
        types: [opened, synchronize]
    
    permissions:
      contents: read
      pull-requests: write
    
    jobs:
      security-review:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
            with:
              fetch-depth: 0
          - uses: anthropics/claude-code-action@v1
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              prompt: |
                You are a security engineer. Review only the security aspects of 
                this PR: authentication, authorization, input validation, injection 
                vulnerabilities, secrets exposure. Post findings as PR review 
                comments with severity: CRITICAL, HIGH, MEDIUM, LOW.
    
      performance-review:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
            with:
              fetch-depth: 0
          - uses: anthropics/claude-code-action@v1
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              prompt: |
                You are a performance engineer. Review this PR for: database 
                query efficiency, caching opportunities, algorithmic complexity, 
                and blocking I/O patterns. Focus on changes that touch the data 
                access layer.
    
      api-contract-review:
        runs-on: ubuntu-latest
        # Only runs when API files change
        if: contains(github.event.pull_request.changed_files, 'src/api/')
        steps:
          - uses: actions/checkout@v4
            with:
              fetch-depth: 0
          - uses: anthropics/claude-code-action@v1
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              prompt: |
                Review this PR for API contract changes. Flag any breaking 
                changes to: request/response shapes, removed endpoints, 
                changed authentication requirements, or modified status codes.
                Cross-reference with the OpenAPI spec in docs/api-spec.yaml.

    Each job runs in parallel, posts its own comments, and can be required or advisory. The PR author sees feedback from three focused reviewers simultaneously.

    Managing Cost and Rate Limits

    Claude Code in CI can get expensive if you're not deliberate about it. Practical cost controls:

    Filter which PRs trigger reviews. Don't run full reviews on every documentation change:

    yamlon:
      pull_request:
        types: [opened, synchronize]
        paths-ignore:
          - '**.md'
          - 'docs/**'
          - '.github/**'
          - '*.txt'

    Set context limits. Claude Code accepts a --max-tokens flag in headless mode. For routine reviews, a tighter context window costs less and forces focused output:

    yaml- name: Claude Review
      run: |
        claude -p "$(cat review-prompt.txt)" \
          --max-turns 3 \
          --output-format json
      env:
        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

    Cache CLAUDE.md parsing. Claude reads CLAUDE.md on every run. Enable prompt caching in your setup to reduce input token costs by up to 90% on repeated context:

    yaml- uses: anthropics/claude-code-action@v1
      with:
        anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
        enable_prompt_caching: true  # Caches CLAUDE.md and system context
        prompt: "Review this PR for security issues."

    Monitor with labels. Add a repository variable CLAUDE_REVIEW_ENABLED: true and check it at the start of your workflow. You can disable automated review without changing workflow files when costs spike unexpectedly.

    Practical Gotchas and Solutions

    Problem: Claude reviews the entire repository instead of just the PR diff. Fix: Explicitly scope the prompt to changed files, and use fetch-depth: 0 with git diff to pass only the relevant diff:

    yaml- name: Get PR diff
      run: |
        git diff origin/${{ github.base_ref }}...HEAD > pr-diff.txt
    
    - name: Claude Review
      uses: anthropics/claude-code-action@v1
      with:
        anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
        prompt: |
          Review the following diff only. Do not read other files unless 
          a specific line in the diff requires understanding context.
          
          $(cat pr-diff.txt)

    Problem: Claude posts too many comments and spams the PR. Fix: Add a comment threshold instruction to CLAUDE.md:

    markdown## Comment Policy (CI Mode)
    Post at most 8 inline comments per review. Prioritize P0 security 
    issues, then P1 bugs, then P2 style. If you find more than 8 issues, 
    post a summary comment listing the remainder rather than individual 
    inline comments.

    Problem: Auto-fix commits break other things downstream. Fix: Run tests after the auto-fix and only commit if they pass:

    yaml- name: Claude Auto-Fix
      uses: anthropics/claude-code-action@v1
      with:
        anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
        prompt: "Fix the failing tests. Make the minimal change needed."
    
    - name: Verify Fix
      run: npm test
      # If this fails, the workflow fails — no broken commit pushed

    Key Takeaways

    • Headless mode (claude -p) makes Claude Code composable with any CI system — it runs the full agent loop and exits
    • claude-code-action is the fastest way to add Claude to GitHub Actions, handling auth and output formatting out of the box
    • CLAUDE.md is your CI policy file — version-control your review standards so they apply consistently across every automated run
    • Parallel specialized agents outperform a single general-purpose review prompt for large codebases
    • Cost controls (path filters, max-turns, prompt caching) keep CI costs predictable as your PR volume grows
    • Test-before-commit guards on auto-fix workflows prevent Claude from pushing regressions

    The shift from manual code review to AI-assisted CI isn't about replacing engineers — it's about removing the boring parts so engineers can focus on the architecture decisions that actually need human judgment.

    Next Steps

    Practice these skills for real exams. The Claude Certified Architect (CCA) exam tests your knowledge of agentic patterns including CI/CD integration, tool use, and multi-agent orchestration — exactly the patterns covered in this guide. AI for Anything's CCA practice test bank covers headless mode, CLAUDE.md configuration, and agent task design with 200+ exam-style questions. Deepen your Claude Code toolkit:

    Ready to Start Practicing?

    300+ scenario-based practice questions covering all 5 CCA domains. Detailed explanations for every answer.

    Free CCA Study Kit

    Get domain cheat sheets, anti-pattern flashcards, and weekly exam tips. No spam, unsubscribe anytime.