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
ANTHROPIC_API_KEYCLAUDE.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 filesThis 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'--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 }}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."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 usefetch-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)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.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 pushedKey Takeaways
- Headless mode (
claude -p) makes Claude Code composable with any CI system — it runs the full agent loop and exits claude-code-actionis the fastest way to add Claude to GitHub Actions, handling auth and output formatting out of the boxCLAUDE.mdis 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:- Claude Code Hooks: Automate Your Dev Workflow — local automation that complements CI pipelines
- Claude Multi-Agent Orchestration Tutorial — coordinate multiple Claude agents for complex tasks
- Claude Tool Use and Function Calling Tutorial — build custom tools for specialized CI tasks
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.