title: "GitHub Actions Workflows for Claude Code" description: "Ready-to-use CI/CD workflows integrating Claude Code into GitHub Actions" tags: [ci-cd, devops, template, workflows]

GitHub Actions Workflows for Claude Code

Ready-to-use GitHub Actions workflows that integrate Claude Code into your CI/CD pipeline.

Prerequisites

1. Install the Claude GitHub App on your org/repo (required for Actions to comment on PRs/issues)
2. Add API Key Secret: In your repo, go to Settings → Secrets and variables → Actions → New repository secret
   • Name: ANTHROPIC_API_KEY
   • Value: Your Anthropic API key from console.anthropic.com
3. Copy Workflows: Place these .yml files in .github/workflows/ directory
4. Test: Open a test PR or issue to see them run

Available Workflows

1. Code Review (Prompt-Based, claude-code-review.yml) ⭐ Recommended

Externalized prompt, anti-hallucination protocol, and /claude-review on-demand trigger.

The review logic lives in .github/prompts/code-review.md, so you can iterate on criteria without touching the workflow YAML. The prompt enforces a verification step before every finding: Claude must confirm an issue with Read/Grep before reporting it.

Features:

• Triggers on PR open/sync/ready and /claude-review comment
• Externalized prompt: edit code-review.md to tune criteria for your stack
• Anti-hallucination protocol: no invented line numbers or unverified claims
• Structured output: 🔴 MUST FIX / 🟡 SHOULD FIX / 🟢 CAN SKIP table + inline comments
• Read-only allowed_tools (no write access to repo)
• OAuth token support (no API key needed if Claude GitHub App is installed)

Setup:

# Copy both files into your repo
cp examples/github-actions/claude-code-review.yml .github/workflows/
mkdir -p .github/prompts
cp examples/github-actions/prompts/code-review.md .github/prompts/

# Add secret: CLAUDE_CODE_OAUTH_TOKEN (or ANTHROPIC_API_KEY)
# Install Claude GitHub App: https://github.com/apps/claude

Customization: Edit .github/prompts/code-review.md to add your stack conventions:

## Stack Context
- TypeScript strict mode, no `any`
- React Server Components, no `useEffect` for data fetching
- All DB writes must go through the repository layer
- New API routes require integration tests

Blocking merge on findings: The gate job in this workflow reads the posted review, parses the ### 🔴 Must Fix (n) count from the summary, and fails the job if n > 0. Add gate to your branch protection's required status checks to turn advisory findings into an actual merge block. Without that branch protection rule, the review still posts but nothing stops a maintainer from merging past it.

2. Code Review (Batched, claude-code-review-batched.yml)

For PRs above a file-count threshold (default 75), a single review pass either times out or spreads Claude's attention too thin across unrelated files. This workflow splits the diff into domain-scoped batches (migrations, backend-core, api-routes, frontend, tests-and-tooling), reviews each batch in a parallel matrix job, then synthesizes one final severity table.

Features:

• check-size job counts changed files and gates the rest of the workflow on the threshold
• Matrix review-batch job: one parallel run per domain, scoped via append_system_prompt
• synthesis job merges all batch comments into a single deduplicated table
• Same prompt file as the non-batched workflow (.github/prompts/code-review.md), no duplicated review criteria to maintain

Setup:

cp examples/github-actions/claude-code-review-batched.yml .github/workflows/

# Edit the `matrix.domain` globs to match your actual directory layout.
# The shipped ones (prisma/migrations, src/server/services, src/components...)
# are a generic starting point, not a fit for every stack.

Run this alongside claude-code-review.yml, not instead of it. Both trigger on the same PR events; the check-size job's threshold is what decides which one actually reviews, so keep BATCH_THRESHOLD consistent if you gate on file count elsewhere too.

3. Auto PR Review (claude-pr-auto-review.yml)

Enhanced version with comprehensive review criteria and smart filtering.

Creates a structured review with inline comments as soon as a PR opens or updates.

Features:

• Automatic code review on PR open/update
• 8 focus areas: Correctness, Security, Performance, Readability, Maintainability, Testing, Best Practices, Breaking Changes
• Priority-based feedback: 🔴 Critical, 🟡 Important, 🟢 Suggestion, 💡 Tip
• Smart file filtering (skips build artifacts, lock files)
• Skips draft PRs to save costs
• Summary review with risk assessment
• Error handling and fallback notifications
• Inline comments on specific lines

Usage:

# Copy the workflow file
cp examples/github-actions/claude-pr-auto-review.yml .github/workflows/

# Open a PR - Claude will automatically review it

Customization: Add project-specific context by uncommenting the append_system_prompt section:

append_system_prompt: |
  Project conventions:
  - Use TypeScript strict mode
  - Follow functional programming patterns
  - All functions must have JSDoc comments
  - Test coverage must be >80%

4. Security Review (claude-security-review.yml)

Runs a focused security scan and comments findings directly on the PR.

Features:

• Security-focused analysis on every PR
• Identifies potential vulnerabilities
• OWASP Top 10 considerations
• Posts findings as PR comments

Configuration:

# Optional parameters in the workflow file:
exclude-directories: "docs,examples"    # Skip certain directories
claudecode-timeout: "20"                # Timeout in minutes
claude-model: "claude-3-5-sonnet-20240620"  # Model to use

Usage:

# Copy the workflow file
cp examples/github-actions/claude-security-review.yml .github/workflows/

# Every PR will be automatically scanned for security issues

5. Issue Triage (claude-issue-triage.yml)

When a new issue opens, Claude proposes labels/severity and posts a tidy triage comment.

Features:

• Automatic issue classification
• Label suggestions
• Severity assessment (low, medium, high, critical)
• Duplicate detection
• Markdown triage comment

Auto-apply Labels (Optional): To automatically apply suggested labels, edit the workflow file and change:

- name: Apply labels (optional)
  if: ${{ false }}  # Change to true to auto-apply labels

Usage:

# Copy the workflow file
cp examples/github-actions/claude-issue-triage.yml .github/workflows/

# Open a new issue - Claude will automatically triage it

Multi-Model Review Setup

Running Claude alongside other automated reviewers (Gemini, Greptile, CodeRabbit) surfaces issues that any single model misses. The pattern: each service reviews independently, then Claude synthesizes the consensus.

Why multi-model? Each model has blind spots. Points raised by 2+ independent reviewers are high-signal; unique catches from each model add coverage you'd otherwise miss.

Recommended stack ($30/month flat)

Alternative: CodeRabbit Pro ($15/dev/month) adds interactive Q&A and sequence diagrams.

Setup

Step 1: Install Gemini Code Assist

1. GitHub Marketplace → search "Gemini Code Assist"
2. Install and authorize on your repo
3. Gemini will automatically review new PRs (posts as gemini-code-assist[bot])
4. Optional config via .gemini/config.yaml:
   yaml复制

   code_review:
     comment_severity_threshold: MEDIUM
     max_comments_per_review: 20

Step 2: Install Greptile

1. greptile.com → connect GitHub account
2. Select your repo, Greptile indexes the codebase (~5 min)
3. Configure in dashboard: target branches, focus paths
4. Reviews post as greptile[bot] comments on PRs
5. Copy .greptile/config.json, .greptile/rules.md, and .greptile/files.json from this directory to your repo root and fill in the placeholders. rules.md is where Greptile's cross-file RAG search earns its keep: business invariants that span multiple files (a state machine enforced in one service but not another, a scoping rule that must hold on every query against a sensitive table). Don't restate rules already covered by .github/prompts/code-review.md or .coderabbit.yaml, split the checklist across the three so each tool owns a distinct set.

Step 3: Enable synthesis job

In claude-code-review.yml, remove false && from the synthesis job condition:

# Before (disabled):
if: |
  false &&
  (github.event_name == 'pull_request' ...

# After (enabled):
if: |
  (github.event_name == 'pull_request' ...

Step 4: Configure CodeRabbit (optional)

Copy .coderabbit.yaml from this directory to your repo root. Edit path_instructions to match your stack.

How the synthesis works

The multi-reviewer-synthesis job in claude-code-review.yml:

1. Waits 5 minutes after the Claude review (external bots post within 2-3 min)
2. Collects all reviews and comments via GitHub API
3. Skips silently if fewer than 2 reviewers have posted
4. Claude identifies consensus (same finding flagged by 2+ reviewers) vs. unique catches
5. Posts a structured synthesis comment on the PR

Scaling to large PRs and repeated pushes

Two problems show up once a repo has real traffic: PRs that touch dozens of files in one go, and PRs that get pushed to five times before merge. Neither is solved by the base workflow above.

Large PRs: switch to claude-code-review-batched.yml above a file-count threshold (see workflow 2). Splitting the diff by domain keeps each batch focused instead of asking one pass to hold the whole PR in context.

Repeated pushes: re-reviewing the full diff on every push burns tokens on code Claude already checked. A delta-review step compares the SHA embedded in the previous review comment (post it as an HTML comment, e.g. ``) against the current push's SHA, and scopes the next review to only the files changed since. This repo does not ship that step as a ready-made template since it depends on how you're already tracking review state (a bot comment, a label, a separate check run); the pattern is: read the last marker, diff git diff <last-sha>..HEAD --name-only, pass that file list into append_system_prompt the same way the batched workflow scopes by domain.

Files in this directory

examples/github-actions/
├── README.md                        # This file
├── claude-code-review.yml           # Main review + gate job + optional synthesis job
├── claude-code-review-batched.yml    # Domain-split matrix review for large PRs
├── .coderabbit.yaml                 # CodeRabbit config (copy to repo root)
├── .greptile/
│   ├── config.json                  # Greptile review config (copy to repo root)
│   ├── rules.md                     # Cross-file invariants rulebook (copy to repo root)
│   └── files.json                   # Doc-to-glob RAG index (copy to repo root)
├── claude-pr-auto-review.yml        # Inline prompt auto-review (alternative)
├── claude-security-review.yml       # Security-focused scan
├── claude-issue-triage.yml          # Issue triage workflow
└── prompts/
    └── code-review.md               # Externalized review prompt (copy to .github/prompts/)

Customization

Model Selection

Set CLAUDE_MODEL or claude-model parameter in workflows:

env:
  CLAUDE_MODEL: claude-3-5-sonnet-20240620

Permissions

Each workflow declares minimal required permissions:

• pull-requests: write for PR reviews
• issues: write for issue triage
• contents: read for reading repository content

Adjust only if your organization requires stricter policies.

Scope Filtering

Use paths: filters to limit when workflows run:

on:
  pull_request:
    paths:
      - 'src/**'
      - '!docs/**'

Troubleshooting

No comments appear on PRs:

• Verify the Claude GitHub App is installed
• Check workflow has pull-requests: write permission

403 when applying labels:

• Ensure the job has issues: write permission
• Verify GITHUB_TOKEN has access to this repo

Anthropic API errors:

• Confirm ANTHROPIC_API_KEY is set at repository level
• Check the key is not expired

YAML syntax errors:

• Validate spacing: two spaces per nesting level, no tabs
• Use a YAML validator: yamllint.com

Advanced Usage

Combining Workflows

Run multiple workflows together for comprehensive automation:

• PR Review + Security Review on every PR
• Issue Triage + Auto-labeling for new issues

Custom Prompts

Edit the direct_prompt section in workflows to customize Claude's focus:

direct_prompt: |
  Review this PR focusing on:
  1. TypeScript type safety
  2. React performance patterns
  3. Accessibility compliance
  4. Test coverage

Integration with Other Actions

Combine with existing workflows:

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - name: Run tests
        run: npm test

  claude-review:
    needs: tests  # Run after tests pass
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@main
        # ...

Cost Considerations

These workflows consume Anthropic API credits:

• PR Review: ~$0.10-$0.50 per review (depending on diff size)
• Security Review: ~$0.20-$0.80 per scan
• Issue Triage: ~$0.05-$0.20 per issue

Tips to reduce costs:

• Use paths: filters to skip docs/config changes
• Set conditions: if: github.event.pull_request.draft == false
• Review logs and adjust model selection

Examples in This Directory

examples/github-actions/
├── README.md                        # This file
├── claude-code-review.yml           # Prompt-based review + gate job + optional synthesis job
├── claude-code-review-batched.yml    # Domain-split matrix review for large PRs
├── .coderabbit.yaml                 # CodeRabbit config (copy to repo root)
├── .greptile/                       # Greptile config templates (copy to repo root)
├── claude-pr-auto-review.yml        # Inline prompt auto-review (alternative)
├── claude-security-review.yml       # Security scanning workflow
├── claude-issue-triage.yml          # Issue triage workflow
└── prompts/
    └── code-review.md               # Externalized review prompt (copy to .github/prompts/)

Resources

• Claude Code Documentation
• GitHub Actions Documentation
• Anthropic API Documentation
• Claude GitHub App

License

These workflows are provided as examples. Adapt them to your needs.