Claude Code GitHub Actions: Complete CI/CD Integration Guide (2026)

Claude Code GitHub Actions makes Claude available as a participant in your GitHub workflow. Post @claude in a PR comment and get an implementation. Open an issue with @claude in the body and get working code back. Set up automated review on every PR without any trigger phrase.

The v1.0 GA release (2026) simplified the configuration significantly compared to the beta and added key features: automatic mode detection, skills integration, and a clean CLI passthrough for all Claude Code flags.

This guide covers setup for both direct API and cloud provider deployments, automated workflows that don’t require manual triggers, and the configuration decisions that affect cost and quality.

What Claude Code GitHub Actions Does

The action runs Claude Code inside a GitHub Actions runner. Claude has access to:

• The repository (via checkout)
• The GitHub API (for PR content, issue details, commenting, creating branches)
• Your configured MCP servers (via claude_args: --mcp-config)
• Skills from .claude/skills/ (after checkout)

Claude can read PR diffs, understand the codebase, implement features, write tests, leave review comments, create branches, and open pull requests — all from a GitHub Actions trigger.

The action is built on the Claude Agent SDK. Every capability available in the SDK is available here.

Quick Setup

Option 1: Automated Setup (Recommended)

Open Claude Code in your terminal:

/install-github-app

This guides you through:

1. Installing the Claude GitHub App on your repository
2. Adding ANTHROPIC_API_KEY to repository secrets
3. Creating the workflow file

Prerequisites: you must be a repository admin. This method works with direct Claude API only — for Bedrock/Vertex, use the manual setup.

Option 2: Manual Setup

Step 1: Install the Claude GitHub App at github.com/apps/claude.

Required permissions:

• Contents: Read & write
• Issues: Read & write
• Pull requests: Read & write

Step 2: Add ANTHROPIC_API_KEY to your repository secrets (Settings → Secrets and variables → Actions).

Step 3: Create .github/workflows/claude.yml:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Test: Post @claude in any PR or issue comment. Claude should respond within 30-60 seconds.

The v1.0 Action Interface

Core Parameters

CLI Passthrough via claude_args

Any Claude Code CLI flag passes through:

claude_args: |
  --max-turns 15
  --model claude-opus-4-8
  --append-system-prompt "Follow our API design standards strictly"
  --mcp-config .claude/mcp-config.json

Migrating from Beta

Full beta example converted:

# Before (beta)
- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "Follow our security checklist"
    max_turns: "10"
    model: "claude-sonnet-4-6"

# After (v1.0)
- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --append-system-prompt "Follow our security checklist"
      --max-turns 10
      --model claude-sonnet-4-6

Workflow Patterns

Interactive: @claude in Comments

The baseline workflow. Claude responds to @claude mentions in PR comments, issue comments, and review comments:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]

jobs:
  claude:
    if: |
      contains(github.event.comment.body, '@claude') ||
      contains(github.event.issue.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Including actions/checkout before the Claude action gives Claude access to skills in .claude/skills/.

Usage examples in PR/issue comments:

@claude implement this feature based on the issue description
@claude review this file for OWASP security issues
@claude add unit tests for the auth module
@claude explain what this function does and why
@claude fix the TypeError in the checkout flow

Automated: PR Review on Every Merge Request

No trigger phrase needed — runs automatically on every PR:

name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request against our coding standards in CLAUDE.md.
            
            Check for:
            - Input validation on all new API endpoints
            - No hardcoded secrets or credentials  
            - Tests for new functionality
            - Proper error handling (no bare catch blocks)
            
            Leave a review comment summarizing findings.
            Use "Request changes" if issues are found, "Approve" if clean.
          claude_args: --max-turns 10

Scheduled: Daily Analysis

name: Daily Code Health
on:
  schedule:
    - cron: "0 9 * * 1-5"  # 9 AM UTC weekdays

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 30  # Enough for recent commit analysis
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Analyze the last 7 days of commits.
            
            Identify:
            1. Files changed most frequently (churn)
            2. Files with no test coverage that were changed
            3. Any TODO comments added this week
            4. Dependencies updated but not in package.json
            
            Create a report at reports/weekly-health.md
          claude_args: --max-turns 20

Skills Integration

Run a skill defined in your repository:

- uses: actions/checkout@v4  # Required to access .claude/skills/

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "/security-review"  # Invokes .claude/skills/security-review/SKILL.md

For a plugin skill:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    plugin_marketplaces: "https://github.com/anthropics/claude-plugins-official.git"
    plugins: "code-review@claude-plugins-official"
    prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

Using CLAUDE.md to Define CI Behavior

Create a CLAUDE.md at your repository root and Claude reads it in every GitHub Actions run, just like in interactive sessions. Use it to define your review criteria without putting everything in the workflow YAML:

# Project: Payment API

## Code Review Criteria
- All payment processing functions must have corresponding integration tests
- No logging of credit card numbers or CVV values (even partial)
- Error messages must not expose internal stack traces to users
- All database queries must use parameterized statements

## Branch Standards
- Never commit directly to main or release/*
- Feature branches must start with feat/ or fix/

## Testing Requirements
- Unit test coverage must not decrease below 85%
- All new API endpoints need both unit and integration tests

This approach separates CI configuration from code — standards live in CLAUDE.md and evolve with the codebase through PR reviews, not buried in workflow YAML.

Enterprise: Amazon Bedrock

Use Bedrock to keep data in your AWS environment, control costs through your AWS billing, and route through your existing security controls.

Prerequisites

1. Enable Claude models in Amazon Bedrock (us-west-2 recommended)
2. Set up GitHub OIDC identity provider in AWS:
   • Provider URL: https://token.actions.githubusercontent.com
   • Audience: sts.amazonaws.com
3. Create IAM role with trust policy for GitHub Actions and AmazonBedrockFullAccess policy
4. Create a custom GitHub App (required for Bedrock — the official Anthropic app is for direct API only)

Workflow

name: Claude PR Review (Bedrock)

permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write  # Required for OIDC

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    env:
      AWS_REGION: us-west-2
    steps:
      - uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-west-2

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_bedrock: "true"
          claude_args: "--model us.anthropic.claude-sonnet-4-6 --max-turns 10"

Note the model ID format for Bedrock: us.anthropic.claude-sonnet-4-6 (region prefix required).

Required Secrets for Bedrock

• AWS_ROLE_TO_ASSUME: ARN of the IAM role (e.g., arn:aws:iam::123456789:role/ClaudeGitHubRole)
• APP_ID: Custom GitHub App ID
• APP_PRIVATE_KEY: Private key .pem content from the custom GitHub App

Enterprise: Google Vertex AI

Keep inference in your GCP project for data residency compliance and GCP billing consolidation.

Prerequisites

1. Enable APIs: IAM Credentials API, Security Token Service API, Vertex AI API
2. Create Workload Identity Pool with GitHub OIDC provider
3. Create Service Account with Vertex AI User role
4. Configure IAM binding for the Workload Identity Pool to impersonate the service account
5. Create custom GitHub App (same requirement as Bedrock)

Workflow

name: Claude PR Review (Vertex)

permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Authenticate to Google Cloud
        id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_vertex: "true"
          claude_args: "--model claude-sonnet-4-5@20250929 --max-turns 10"
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5

Required Secrets for Vertex AI

• GCP_WORKLOAD_IDENTITY_PROVIDER: Full provider resource name
• GCP_SERVICE_ACCOUNT: Service account email
• APP_ID and APP_PRIVATE_KEY: Custom GitHub App credentials

Security Best Practices

API Key Management

# Always use secrets — never hardcode
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# Wrong — exposed in workflow file
anthropic_api_key: "sk-ant-..."

Permissions Scoping

Set the minimum required permissions at the job level:

permissions:
  contents: write      # For creating branches and committing
  pull-requests: write # For creating PRs and leaving reviews
  issues: write        # For reading issues and commenting
  # id-token: write    # Only add this for OIDC (Bedrock/Vertex)

Limiting What Claude Can Do

Use claude_args to restrict tools:

# Read-only analysis agent
claude_args: "--allowedTools Read,Glob,Grep,Bash(git log *),Bash(git diff *)"

# Or use Plan Mode for pure analysis
claude_args: "--permission-mode plan"

Use CLAUDE.md to define behavioral constraints. Use --append-system-prompt for workflow-specific restrictions:

claude_args: |
  --append-system-prompt "Do not push to main. Do not merge PRs. Create branches with prefix claude/."
  --max-turns 15

Concurrency Control

Prevent Claude from running multiple times simultaneously on the same PR:

concurrency:
  group: claude-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

Cost Optimization

Limit Turns

Default is 10. Lower for simple tasks, higher for complex implementations:

# For code review (read-heavy, low complexity)
claude_args: "--max-turns 5"

# For feature implementation (needs exploration + implementation)
claude_args: "--max-turns 20"

Trigger Filtering

Don’t run Claude on every PR event — be specific:

on:
  pull_request:
    types: [opened, synchronize]  # Not: edited, labeled, assigned, etc.
    paths:                         # Only when source files change
      - "src/**"
      - "tests/**"

Job Timeout

Prevent runaway jobs:

jobs:
  claude:
    runs-on: ubuntu-latest
    timeout-minutes: 15  # Fail after 15 minutes

Model Selection

Match the model to the task:

# For PR review (quality matters, worth the cost)
claude_args: "--model claude-sonnet-4-6"

# For simple classification tasks
claude_args: "--model claude-haiku-4-5"

# For complex multi-file implementation
claude_args: "--model claude-opus-4-8"

Troubleshooting

@claude Not Responding

1. Check that the Claude GitHub App is installed on the repository (not just the organization)
2. Verify ANTHROPIC_API_KEY is set in repository secrets (not organization secrets, unless you’ve explicitly enabled them for this repo)
3. Check the Actions tab for failed workflows — look for authentication errors
4. Confirm the comment contains exactly @claude (not /claude or @ claude)

Claude’s Changes Not Triggering CI

The Claude GitHub App or your custom app must have permission to trigger subsequent CI workflows. Using the official Anthropic app: CI triggers work. Using a custom GitHub App: ensure it has the same permissions.

Alternatively, set the GITHUB_TOKEN input to a PAT that can trigger workflows:

github_token: ${{ secrets.GH_PAT_WITH_WORKFLOW }}

Authentication Errors with Bedrock/Vertex

For Bedrock: verify the IAM role trust policy includes the correct repository path. The condition must match repo:owner/repo-name:*.

For Vertex: run gcloud auth list in a test workflow to verify the service account is active. Check that ANTHROPIC_VERTEX_PROJECT_ID and CLOUD_ML_REGION are set correctly.

Real Examples from the Examples Directory

The examples directory includes ready-to-use workflows for:

• Basic @claude trigger
• Automated PR review
• Scheduled analysis
• Bedrock and Vertex AI deployments
• Custom GitHub App authentication

Copy them as starting points and adjust for your team’s workflow and CLAUDE.md standards.

Internal Links

• Claude Code Routines: Schedule, API, and GitHub Automation — Cloud-based automation vs. GitHub Actions
• Claude Agent SDK: Build Custom Agents — GitHub Actions is built on the Agent SDK
• Claude Code Skills vs Slash Commands — Skills you can invoke from GitHub Actions
• Claude Code Memory System — CLAUDE.md files Claude reads in CI runs
• Claude Code Permission Modes — Permission configuration for CI environments