Claude Code GitHub Actions

Claude Code GitHub Actions brings AI-driven automation to your GitHub workflows.

By simply mentioning it in a PR or Issue@claude, Claude can analyze code, create Pull Requests, implement features, and fix bugs while following your project's standard guidelines.

Why use Claude Code GitHub Actions

  • Instant PR creation: Describe your needs, and Claude can create a complete Pull Request
  • Automated code implementation: Turn Issues into working code with just one command
  • Follows project standards: Respects yourCLAUDE.mdguidelines and existing code patterns
  • Simple and fast: Get started in minutes
  • Secure and reliable: Code stays running on GitHub's runners

Quick Start

Method 1: Automatic Installation (Recommended)

Run in the Claude Code terminal:

/install-github-app

This will guide you through:

  • Setting up a GitHub App
  • Adding required Secrets

Requirements: You must be a repository administrator. The GitHub App needs read/write permissions for Contents, Issues, and Pull requests. Only applicable to users directly using the Claude API (AWS Bedrock and Google Vertex AI are not supported).

Method 2: Manual Installation

Step 1: Install the Claude GitHub App

Visit:https://github.com/apps/claude

Required permissions:

  • Contents: Read/write permissions
  • Issues: Read/write permissions
  • Pull requests: Read/write permissions

Step 2: Add API key

Add to repository SecretsANTHROPIC_API_KEY

Step 3: Create workflow file

Copy from example file:examples/claude.ymlto.github/workflows/

Workflow Configuration

Basic Workflow (Respond to @claude mentions)

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Automatic Code Review

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this pull request for code quality, correctness, and security."
          claude_args: "--max-turns 5"

Scheduled Tasks

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model opus"

Common @claude Commands

Use in PR or Issue comments:

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component
@claude review this PR for security issues
@claude add tests for this new function

Action Parameters Explained

Parameter Description Required
prompt Instructions for Claude (plain text or skill name) No*
claude_args CLI arguments passed to Claude Code no
anthropic_api_key Claude API Key Yes**
github_token GitHub Token (for API access) no
trigger_phrase Custom trigger word (default:@claude） no
use_bedrock Use AWS Bedrock instead of Claude API no
use_vertex Use Google Vertex AI instead of Claude API no

*Omit prompt when used in issue/PR comments; Claude responds to the trigger word

**Required when using Claude API directly, not needed for Bedrock/Vertex

Common CLI Parameters

Parameter Description
--max-turns Maximum conversation turns (default 10)
--model Model to use (e.g.claude-sonnet-4-6）
--mcp-config MCP configuration file path
--allowedTools Allowed tools (comma-separated)
--append-system-prompt Append system prompt
--debug Enable debug output

claude_args Examples

claude_args: |
  --max-turns 5
  --model claude-sonnet-4-6
  --mcp-config /path/to/config.json
  --append-system-prompt "Follow our coding standards"

AWS Bedrock Integration

Prerequisites

  • AWS Bedrock access enabled with Claude model permissions
  • GitHub configured as OIDC identity provider in AWS
  • IAM role with Bedrock permissions

Required Secrets

Secret Name Description
AWS_ROLE_TO_ASSUME IAM role ARN for Bedrock access
APP_ID GitHub App ID
APP_PRIVATE_KEY GitHub App private key

Bedrock Workflow Example

name: Claude PR Action
permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

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

jobs:
  claude-pr:
    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'))
    runs-on: ubuntu-latest
    env:
      AWS_REGION: us-west-2
    steps:
      - name: Checkout repository
        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 (OIDC)
        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'

Google Vertex AI Integration

Prerequisites

  • Vertex AI API enabled in GCP project
  • Workload Identity Federation configured for GitHub
  • Service account with Vertex AI permissions

Required Secrets

Secret Name Description
GCP_WORKLOAD_IDENTITY_PROVIDER Workload Identity Provider resource name
GCP_SERVICE_ACCOUNT Service account email with Vertex AI access
APP_ID GitHub App ID
APP_PRIVATE_KEY GitHub App private key

Vertex AI Workflow Example

name: Claude PR Action
permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]

jobs:
  claude-pr:
    if: github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        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 }}
          trigger_phrase: "@claude"
          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

Upgrading from Beta (v1.0 Breaking Changes)

Beta Input New v1.0 Input
mode (Removed - auto-detected)
direct_prompt prompt
override_prompt with GitHub variablesprompt
custom_instructions claude_args: --append-system-prompt
max_turns claude_args: --max-turns
model claude_args: --model
allowed_tools claude_args: --allowedTools
disallowed_tools claude_args: --disallowedTools

Before and After Upgrade Comparison

Beta version:

- 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 coding standards"
    max_turns: "10"
    model: "claude-sonnet-4-6"

GA version (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 coding standards"
      --max-turns 10
      --model claude-sonnet-4-6

Troubleshooting

Claude does not respond to @claude commands

  • Confirm GitHub App is installed correctly
  • Check that the workflow is enabled
  • Ensure API key is set in repository Secrets
  • Confirm the comment contains@claude(not/claude）

CI does not run on Claude's commits

  • Use GitHub App or custom app (don't use the Actions user)
  • Check workflow triggers include necessary events
  • Confirm app permissions include CI triggers

Authentication Errors

  • Confirm API key is valid and has sufficient permissions
  • For Bedrock/Vertex: check credential configuration
  • Ensure Secret names are correct in the workflow

Security Considerations

  • Never commit API keys directlyto the repository
  • Use GitHub Secrets to store API keys:${{ secrets.ANTHROPIC_API_KEY }}
  • Limit action permissions; grant only necessary permissions
  • Review Claude's suggestions before merging
  • For AWS/GCP: use OIDC identity providers instead of static credentials
  • Create dedicated service accounts for each repository

Cost Considerations

Cost Breakdown

  • GitHub Actions costs: Running on GitHub-hosted runners consumes GitHub Actions minutes
  • API costs: Each Claude interaction consumes API tokens based on prompt/response length

Cost Optimization Suggestions

  • Use specific@claudecommands, reduce unnecessary API calls
  • Configure appropriate--max-turnsLimit conversation rounds
  • Set workflow timeouts to prevent tasks from running out of control
  • Use GitHub concurrency controls to limit parallel runs

Best Practices

1. Create CLAUDE.md

Create in repository rootCLAUDE.mdfile, define code style guide and project-specific rules:

# 项目开发规范

## 代码风格
- 使用 TypeScript 4.x
- 遵循 ESLint 配置
- 函数必须有 JSDoc 注释

## PR 要求
- 必须通过所有 CI 检查
- 至少一个代码审查
- 更新相关文档

## 禁止事项
- 不要修改 `migrations/` 目录
- 不要提交 `.env` 文件

2. Use specific @claude commands

@claude review this PR for SQL injection vulnerabilities
@claude add unit tests for the new validateEmail function

3. Configure appropriate limits

jobs:
  claude:
    runs-on: ubuntu-latest
    timeout-minutes: 15  # 设置超时
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          claude_args: "--max-turns 5 --allowedTools Read,Grep,Glob,Bash,Write,Edit"

4. CI/CD Automation Scenarios

  • PR automatic review: Automatically trigger review when PR is opened or updated
  • Issue auto-classification: Automatically add labels and assignees when new Issue is created
  • Scheduled reports: Generate daily code statistics or security reports
  • Automated fixes: Automatically analyze and attempt fixes when CI fails
Other extensions