Claude Code GitHub Actions Complete Guide | Automate PRs and Code Reviews with AI

Claude Code GitHub Actions brings AI-powered automation to your GitHub workflows. Simply mention @claude in any Issue or PR, and Claude can analyze code, create pull requests, implement features, and fix bugs automatically.

What is Claude Code GitHub Actions?

Claude Code GitHub Actions integrates Anthropic’s Claude AI into your GitHub Actions workflow. Developers can delegate routine coding tasks to AI, significantly improving development efficiency.

Key Features

• Instant PR Generation: Describe your needs and get complete PRs with all changes
• Auto Implementation: Convert Issues to working code with a single command
• Code Review: Automatically analyze PRs for bugs, style, and coding standards
• Bug Fixes: Find and fix errors, creating merge-ready PRs automatically
• Standards Compliance: Automatically follows CLAUDE.md guidelines and existing patterns

Pricing Models

Two ways to use Claude Code GitHub Actions:

Method Billing Features

API Pay-per-use Per token usage Pay only for what you use

Max Subscription Monthly flat rate Available with Max 5x or higher plans

As of July 2025, Max Subscription users can now use this feature.

Setup Methods

Method 1: Quick Setup (Recommended)

The easiest method uses Claude Code’s install command.

Prerequisites:

• Claude Code installed
• Logged into GitHub account

Steps:

# Launch Claude Code
claude

# Run the install command
/install-github-app

This command will:

1. Display GitHub App Installation Screen
   1. Select your repository
   2. Review required permissions for the “Claude” app
   3. Click “Install”
2. Automatically Create a PR
   1. PR with .github/workflows/claude.yml is created
   2. Browser opens to the PR page
3. Merge the PR to Complete Setup

Method 2: Manual Setup

If /install-github-app fails or you prefer manual setup:

Step 1: Install Claude GitHub App

Visit https://github.com/apps/claude and install the app on your repository.

Step 2: Add API Key to Secrets

For API Pay-per-use:

1. Go to repository “Settings” → “Secrets and variables” → “Actions”
2. Click “New repository secret”
3. Configure:
   1. Name: ANTHROPIC_API_KEY
   2. Value: Your API key from Anthropic Console

For Max Subscription:

Generate a token in your terminal:

claude setup-token

Open the displayed URL in your browser and click “Authorize”. Copy the issued token (string starting with sk).

Set in GitHub:

• Name: CLAUDE_CODE_OAUTH_TOKEN
• Value: The issued token

Step 3: Create Workflow File

Create .github/workflows/claude.yml:

name: Claude Code

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) ||
      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

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

How to Use

Basic Usage

Simply mention @claude in Issue or PR comments.

Request Code Review

In a PR comment:

@claude Please review this PR, focusing especially on security aspects.

Request Bug Fix

In an Issue:

@claude Please create a PR to fix this bug.

Request Feature Implementation

In an Issue:

@claude Please implement this feature and create a PR.

Advanced Usage

Configure Rules with CLAUDE.md

Create a CLAUDE.md file at your repository root to customize Claude’s behavior:

# Project Rules

## Coding Style
- Use TypeScript
- Add JSDoc comments to functions
- Maintain 80%+ test coverage

## Review Criteria
- Prioritize security risk checks
- Evaluate performance impact
- Follow existing code style

Use Custom Commands

Set custom prompts in your workflow file:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Write review comments in English"
    claude_args: "--max-turns 10 --model claude-sonnet-4-5-20250929"

Configuration Parameters

Key parameters available in v1.0:

Parameter Description Required

prompt Instructions or slash commands for Claude No

claude_args CLI arguments (--max-turns, --model, etc.) No

anthropic_api_key Claude API key *

claude_code_oauth_token Token for Max Subscription *

github_token GitHub token (auto-configured by default) No

use_bedrock Use AWS Bedrock No

use_vertex Use Google Vertex AI No

• Either anthropic_api_key or claude_code_oauth_token is required

Cloud Provider Integration

AWS Bedrock Integration

Example workflow using AWS Bedrock:

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::123456789012:role/claude-github-actions
    aws-region: us-east-1

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"

Required IAM permissions:

• bedrock:InvokeModel
• bedrock:InvokeModelWithResponseStream

Google Vertex AI Integration

- name: Authenticate to Google Cloud
  uses: google-github-actions/auth@v2
  with:
    workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github/providers/github
    service_account: claude-github-actions@project.iam.gserviceaccount.com

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    use_vertex: "true"
  env:
    ANTHROPIC_VERTEX_PROJECT_ID: your-project-id
    CLOUD_ML_REGION: us-east5

Best Practices

Cost Optimization

1. Set Appropriate max-turns

claude_args: "--max-turns 5"

• Configure Workflow Timeout

jobs:
  claude:
    timeout-minutes: 30

• Trigger Only on Specific Events
  • Run only when @claude mention is present
  • Prevent unnecessary workflow runs

Security

1. Secret Management
   1. Always manage API keys with GitHub Secrets
   2. Never hardcode in files
2. Principle of Least Privilege
   1. Grant only necessary permissions
   2. id-token: write only for OIDC authentication
3. Beware of Fork PRs
   1. Secrets are not available in PRs from forks
   2. Design with security risks in mind

Troubleshooting

Claude Not Responding

Check:

1. Is the GitHub App installed on the repository?
2. Is the workflow file correctly placed?
3. Using @claude (not /claude)?
4. Are secrets correctly configured?

Authentication Errors

API Key Related:

Error: Invalid API key

• Verify API key validity
• Confirm secret name is ANTHROPIC_API_KEY
• Check if key has sufficient credits

Max Subscription Related:

Error: OAuth token invalid

• Reissue token with claude setup-token
• Confirm secret name is CLAUDE_CODE_OAUTH_TOKEN

CI Not Running

Check:

• Workflow file syntax errors
• Trigger event configuration
• Branch protection rules

Upgrading to v1.0

Required changes when migrating from beta to v1.0:

Item Beta v1.0

Action version @beta @v1

Mode setting mode: "agent" Remove (auto-detected)

Prompt direct_prompt prompt

Upgrade Example:

# Beta
- uses: anthropics/claude-code-action@beta
  with:
    mode: "agent"
    direct_prompt: "Please review"

# v1.0
- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Please review"

Use Cases

Auto Code Review Workflow

name: Auto Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Please review this PR thoroughly:
            - Security perspective
            - Performance impact
            - Coding style consistency
            - Test coverage

Auto Issue Response Workflow

name: Auto Issue Response

on:
  issues:
    types: [labeled]

jobs:
  respond:
    if: github.event.label.name == 'claude-fix'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Please create a PR to fix this Issue"

Summary

With Claude Code GitHub Actions, you can:

• Improve Development Efficiency: Delegate routine tasks to AI
• Enhance Code Quality: Consistent review standards
• Rapid Bug Response: Auto-generated fix PRs
• Boost Team Collaboration: Anyone can request help with @claude

Setup is complete with just the /install-github-app command. Start using Claude Code GitHub Actions today and experience AI-powered development workflows.

References

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