Claude Code CI/CD Integration Guide — GitHub Actions

Integrating Claude Code with GitHub Actions enables you to automate code reviews, respond to issues, and generate code directly within your GitHub workflows. This guide covers both quick setup and advanced configurations for production environments.

Overview

Claude Code GitHub Actions integration allows you to:

• Automated PR Reviews: Use Claude to review pull requests and provide intelligent feedback
• Issue Handling: Automatically respond to issues and generate solutions
• Code Generation: Create code based on issue descriptions or comments
• Intelligent Comments: Mention @claude in PR comments to trigger analysis
• Multi-Model Support: Leverage AWS Bedrock and Google Vertex AI integrations

The integration uses the official anthropics/claude-code-action@v1 GitHub Action, which supports multiple triggers including pull requests, issue comments, and pull request review comments.

Quick Setup with Claude CLI

The fastest way to get started is using the Claude CLI's installation command. This automates most of the configuration for you.

Prerequisites

• GitHub repository with admin access
• Anthropic API key (from console.anthropic.com)
• Claude CLI installed on your machine

Installation Steps

Run the quick setup command:

/install-github-app

This command will:

1. Automatically install the Claude GitHub App to your repository
2. Create the required ANTHROPIC_API_KEY secret
3. Set up a basic workflow file with sensible defaults
4. Configure repository permissions for Contents, Issues, and Pull Requests

After running this command, the integration is immediately active and ready to respond to PR reviews, issue comments, and pull request review comments.

Tip: The quick setup uses default parameters optimized for most projects. For advanced configurations, refer to the manual setup section.

Manual Setup

If you prefer more control over the configuration or need to troubleshoot, follow these manual setup steps.

Step 1: Install the Claude GitHub App

1. Visit the Claude GitHub App installation page
2. Select your GitHub account or organization
3. Choose the repositories where you want to use Claude Code
4. Grant the required permissions (see Permissions section below)
5. Complete the installation

Step 2: Add the API Key Secret

1. Go to your repository settings
2. Navigate to Secrets and variables → Actions
3. Click New repository secret
4. Name it ANTHROPIC_API_KEY
5. Paste your Anthropic API key from console.anthropic.com
6. Click Add secret

Security Note: Never commit your API key to your repository. Always use GitHub secrets for sensitive credentials.

Step 3: Create the Workflow File

Create a new file in your repository at .github/workflows/claude-code.yml:

name: Claude Code Integration
 
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  pull_request:
    types: [opened, synchronize]
 
jobs:
  claude-code:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write
 
    steps:
      - name: Run Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          trigger_phrase: '@claude'
          claude_args: '--max-turns=5'

Commit this file to your repository's main branch to activate the integration.

Repository Permissions

The Claude Code GitHub Action requires specific permissions to function properly. Configure these in your workflow file or repository settings.

Ensure your workflow includes the correct permissions block:

permissions:
  contents: read
  issues: write
  pull-requests: write

Workflow Triggers

The Claude Code Action responds to multiple trigger types. Understanding these helps you optimize when Claude engages with your repository.

Trigger Types

Issue Comments (issue_comment)

• Activated when someone comments on an issue
• Use @claude mentions to request analysis or code generation
• Great for follow-up discussions and clarifications

Pull Request Review Comments (pull_request_review_comment)

• Triggered by comments on PR diffs
• Allows Claude to respond to inline code suggestions
• Enables targeted feedback on specific code sections

Pull Request Events (pull_request)

• Runs when PRs are opened or updated
• Useful for automatic PR reviews
• Can trigger on specific branches using branches filter

Example: Conditional Triggers

on:
  pull_request:
    types: [opened, synchronize]
    branches:
      - main
      - develop
  issue_comment:
    types: [created]

Configuration Parameters

The Claude Code Action supports multiple parameters to customize behavior and capabilities.

Parameter Reference Table

Parameter Examples

With AWS Bedrock:

- name: Run Claude Code with Bedrock
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    use_bedrock: true
    claude_args: '--model=bedrock-claude-3-sonnet --max-turns=5'

With Google Vertex AI:

- name: Run Claude Code with Vertex AI
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    use_vertex: true
    claude_args: '--model=vertex-claude-3-opus --max-turns=8'

Custom System Prompt:

- name: Run Claude Code with Custom Prompt
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "You are a code review expert focusing on security and performance."

Common Use Cases

Automated PR Reviews

Automatically review PRs for code quality, security issues, and best practices:

name: Automated PR Review
 
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
 
    steps:
      - name: Check out code
        uses: actions/checkout@v4
 
      - name: Review with Claude
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this code for:
            1. Security vulnerabilities
            2. Performance issues
            3. Code style and best practices
            4. Test coverage

Issue Response Automation

Automatically respond to new issues with analysis and solution suggestions:

name: Issue Response
 
on:
  issues:
    types: [opened]
 
jobs:
  respond:
    runs-on: ubuntu-latest
    permissions:
      issues: write
 
    steps:
      - name: Analyze and Respond
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Analyze this GitHub issue and provide:
            1. Root cause analysis
            2. Proposed solution
            3. Affected components

Code Generation from Issues

Generate code implementations based on feature requests:

name: Code Generation
 
on:
  issue_comment:
    types: [created]
 
jobs:
  generate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
 
    steps:
      - name: Generate Code
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          trigger_phrase: '/generate'
          prompt: "Generate production-ready code with full test coverage"

The /review Skill

The /review skill provides specialized PR review capabilities when mentioned in comments:

@claude /review

When invoked, Claude will:

• Analyze all files changed in the PR
• Provide detailed feedback on each change
• Suggest improvements and alternatives
• Check for potential bugs and edge cases
• Verify adherence to project standards

Using /review Effectively

Comment on a PR with:

@claude /review --focus=security,performance

Additional focus options:

• security: Check for vulnerabilities
• performance: Identify optimization opportunities
• tests: Evaluate test coverage
• documentation: Review code documentation
• all: Comprehensive review (default)

PR Creation from Issues

Claude can create pull requests directly from issues when requested:

@claude /create-pr "Implement user authentication system"

This workflow:

1. Creates a feature branch from the issue
2. Generates code based on issue requirements
3. Creates a pull request with the generated code
4. Links the PR back to the original issue
5. Runs initial tests and checks

Environment-Specific Configuration

Development Workflow

name: Development Workflow
 
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
 
jobs:
  claude-assist:
    runs-on: ubuntu-latest
    if: github.event.issue.draft == false
    permissions:
      contents: read
      issues: write
      pull-requests: write
 
    steps:
      - name: Assist with Development
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: '--max-turns=8 --model=claude-opus-4'
          trigger_phrase: '@claude'

Production Review Workflow

name: Production Review
 
on:
  pull_request:
    types: [opened, synchronize]
    branches:
      - main
      - production
 
jobs:
  strict-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
 
    steps:
      - name: Strict Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: '--max-turns=3 --strict-mode'
          prompt: |
            You are a production code reviewer.
            Block merging if you identify:
            - Security vulnerabilities
            - Performance regressions
            - Breaking API changes
            - Missing tests for critical paths

Best Practices

1. Use a CLAUDE.md File

Create a CLAUDE.md file in your repository root to provide context:

# CLAUDE.md
 
## Project Overview
- **Name**: MyApp
- **Language**: TypeScript
- **Framework**: Next.js
 
## Code Standards
- Use functional components with hooks
- Follow ESLint configuration strictly
- Maintain 80%+ test coverage
- Document all public APIs
 
## Architecture Decisions
- Store service with Redux
- API routes in `/api` directory
- Database: PostgreSQL with Prisma ORM
 
## Common Commands
- `npm run dev`: Start development server
- `npm test`: Run test suite
- `npm run build`: Create production build

Claude will reference this file to maintain consistency with your project standards.

2. Never Commit Secrets

Always use GitHub secrets for API keys:

# ✅ Correct
with:
  anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 
# ❌ Never hardcode keys
with:
  anthropic_api_key: sk-ant-xxxxx

3. Control Turn Limits

Set appropriate --max-turns values to control API costs:

# For quick checks
claude_args: '--max-turns=2'
 
# For detailed analysis
claude_args: '--max-turns=5'
 
# For complex generation
claude_args: '--max-turns=8'

4. Use Concurrency Controls

Prevent multiple runs from conflicting:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

5. Monitor API Usage

Log Claude's activity for monitoring:

- name: Claude Code Review
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
  env:
    CLAUDE_LOG_LEVEL: verbose

6. Implement Rate Limiting

Protect your API quota:

- name: Rate-Limited Claude Review
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: '--rate-limit=10-per-hour'

7. Use Conditional Workflows

Only run Claude on relevant changes:

jobs:
  claude-review:
    if: |
      contains(github.event.pull_request.labels.*.name, 'needs-review') ||
      contains(github.event.issue.labels.*.name, 'code-generation')
    runs-on: ubuntu-latest
    # ... rest of job

Troubleshooting

Claude Not Responding

Issue: Comments with @claude mentions aren't triggering responses.

Solutions:

• Verify ANTHROPIC_API_KEY secret is set correctly
• Check that the workflow file is on the default branch
• Ensure workflow permissions include issues: write and pull-requests: write
• Check GitHub Actions is enabled in repository settings

API Key Errors

Issue: "Invalid API key" or "Authentication failed" errors.

Solutions:

• Confirm the API key is active on console.anthropic.com
• Verify the secret name matches exactly in the workflow
• Regenerate the API key if unsure of validity
• Check for accidental spaces or special characters

Rate Limiting

Issue: Claude frequently hits rate limits.

Solutions:

• Reduce --max-turns to lower API calls
• Implement workflow concurrency controls
• Add delays between trigger conditions
• Consider using Bedrock for higher limits

Permission Errors

Issue: "Insufficient permissions" errors in logs.

Solutions:

• Verify permissions block in workflow file
• Check organization-level restrictions
• Ensure app has necessary GitHub permissions
• Review branch protection rule configurations

Advanced Integration Patterns

Multi-Model Comparison

Use different models for different purposes:

jobs:
  quick-review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: '--model=claude-3-haiku'
 
  detailed-review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: '--model=claude-opus-4'

Multi-Cloud Deployment

Leverage different infrastructure providers:

steps:
  - name: Review with Bedrock
    uses: anthropics/claude-code-action@v1
    if: github.actor == 'trusted-user'
    with:
      use_bedrock: true
 
  - name: Review with Vertex
    uses: anthropics/claude-code-action@v1
    if: github.actor != 'trusted-user'
    with:
      use_vertex: true

Monitoring and Analytics

Tracking Claude Activity

Monitor how Claude is being used:

- name: Claude Code Review
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
  env:
    ANALYTICS_ENDPOINT: ${{ secrets.ANALYTICS_URL }}

Measuring Impact

Track metrics like:

• Average time from issue to PR creation
• Code review turnaround time
• Bug detection rate improvement
• Developer satisfaction scores

Wrapping up

Claude Code's GitHub Actions integration brings AI-powered automation to your development workflow. Start with the quick setup for immediate benefits, then explore advanced configurations as your team's needs evolve.

Remember to:

• Keep API keys secure
• Monitor API usage and costs
• Provide clear context with CLAUDE.md
• Test configurations in development branches
• Review Claude's output before merging

For more information, visit the Claude documentation or GitHub repository.