Claude Code GitHub Actions

Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow. With a simple @claude mention in any PR or issue, Claude can analyze your code, create pull requests, implement features, and fix bugs - all while following your project’s standards.

Claude Code GitHub Actions is built on top of the Claude Code SDK, which enables programmatic integration of Claude Code into your applications. You can use the SDK to build custom automation workflows beyond GitHub Actions.

Why use Claude Code GitHub Actions?

Instant PR creation: Describe what you need, and Claude creates a complete PR with all necessary changes
Automated code implementation: Turn issues into working code with a single command
Follows your standards: Claude respects your CLAUDE.md guidelines and existing code patterns
Simple setup: Get started in minutes with our installer and API key
Secure by default: Your code stays on Github’s runners

What can Claude do?

Claude Code provides a powerful GitHub Action that transforms how you work with code:

Claude Code Action

This GitHub Action allows you to run Claude Code within your GitHub Actions workflows. You can use this to build any custom workflow on top of Claude Code. View repository →

Setup

Quick setup

The easiest way to set up this action is through Claude Code in the terminal. Just open claude and run /install-github-app. This command will guide you through setting up the GitHub app and required secrets.

You must be a repository admin to install the GitHub app and add secrets - This quickstart method is only available for direct Anthropic API users. If you’re using AWS Bedrock or Google Vertex AI, please see the Using with AWS Bedrock & Google Vertex AI section.

Manual setup

If the /install-github-app command fails or you prefer manual setup, please follow these manual setup instructions:

Install the Claude GitHub app to your repository: https://github.com/apps/claude
Add ANTHROPIC_API_KEY to your repository secrets (Learn how to use secrets in GitHub Actions)
Copy the workflow file from examples/claude.yml into your repository’s .github/workflows/

After completing either the quickstart or manual setup, test the action by tagging @claude in an issue or PR comment!

Upgrading from Beta

Claude Code GitHub Actions v1.0 introduces breaking changes that require updating your workflow files in order to upgrade to v1.0 from the beta version.

If you’re currently using the beta version of Claude Code GitHub Actions, we recommend that you update your workflows to use the GA version. The new version simplifies configuration while adding powerful new features like automatic mode detection.

Essential changes

All beta users must make these changes to their workflow files in order to upgrade:

Update the action version: Change @beta to @v1
Remove mode configuration: Delete mode: "tag" or mode: "agent" (now auto-detected)
Update prompt inputs: Replace direct_prompt with prompt
Move CLI options: Convert max_turns, model, custom_instructions, etc. to claude_args

Breaking Changes Reference

Old Beta Input	New v1.0 Input
`mode`	(Removed - auto-detected)
`direct_prompt`	`prompt`
`override_prompt`	`prompt` with GitHub variables
`custom_instructions`	`claude_args: --system-prompt`
`max_turns`	`claude_args: --max-turns`
`model`	`claude_args: --model`
`allowed_tools`	`claude_args: --allowedTools`
`disallowed_tools`	`claude_args: --disallowedTools`
`claude_env`	`settings` JSON format

Before and After Example

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-3-5-sonnet-20241022"

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: |
      --system-prompt "Follow our coding standards"
      --max-turns 10
      --model claude-sonnet-4-20250514

The action now automatically detects whether to run in interactive mode (responds to @claude mentions) or automation mode (runs immediately with a prompt) based on your configuration.

Example use cases

Claude Code GitHub Actions can help you with a variety of tasks. The examples directory contains ready-to-use workflows for different scenarios.

Basic workflow

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 }}
          # Responds to @claude mentions in comments

Using slash commands

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"
          claude_args: "--max-turns 5"

Custom automation with prompts

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 claude-opus-4-1-20250805"

Common use cases

In issue or PR 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 will automatically analyze the context and respond appropriately.

Best practices

CLAUDE.md configuration

Create a CLAUDE.md file in your repository root to define code style guidelines, review criteria, project-specific rules, and preferred patterns. This file guides Claude’s understanding of your project standards.

Security considerations

Never commit API keys directly to your repository!

Always use GitHub Secrets for API keys:

Add your API key as a repository secret named ANTHROPIC_API_KEY
Reference it in workflows: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
Limit action permissions to only what’s necessary
Review Claude’s suggestions before merging

Always use GitHub Secrets (e.g., ${{ secrets.ANTHROPIC_API_KEY }}) rather than hardcoding API keys directly in your workflow files.

Optimizing performance

Use issue templates to provide context, keep your CLAUDE.md concise and focused, and configure appropriate timeouts for your workflows.

CI costs

When using Claude Code GitHub Actions, be aware of the associated costs: GitHub Actions costs:

Claude Code runs on GitHub-hosted runners, which consume your GitHub Actions minutes
See GitHub’s billing documentation for detailed pricing and minute limits

API costs:

Each Claude interaction consumes API tokens based on the length of prompts and responses
Token usage varies by task complexity and codebase size
See Claude’s pricing page for current token rates

Cost optimization tips:

Use specific @claude commands to reduce unnecessary API calls
Configure appropriate --max-turns in claude_args to prevent excessive iterations
Set workflow-level timeouts to avoid runaway jobs
Consider using GitHub’s concurrency controls to limit parallel runs

Configuration examples

The Claude Code Action v1 simplifies configuration with unified parameters:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Your instructions here" # Optional
    claude_args: "--max-turns 5" # Optional CLI arguments

Key features:

Unified prompt interface - Use prompt for all instructions
Slash commands - Pre-built prompts like /review or /fix
CLI passthrough - Any Claude Code CLI argument via claude_args
Flexible triggers - Works with any GitHub event

Visit the examples directory for complete workflow files.

When responding to issue or PR comments, Claude automatically responds to @claude mentions. For other events, use the prompt parameter to provide instructions.

Using with AWS Bedrock & Google Vertex AI

For enterprise environments, you can use Claude Code GitHub Actions with your own cloud infrastructure. This approach gives you control over data residency and billing while maintaining the same functionality.

Prerequisites

Before setting up Claude Code GitHub Actions with cloud providers, you need:

For Google Cloud Vertex AI:

A Google Cloud Project with Vertex AI enabled
Workload Identity Federation configured for GitHub Actions
A service account with the required permissions
A GitHub App (recommended) or use the default GITHUB_TOKEN

For AWS Bedrock:

An AWS account with Amazon Bedrock enabled
GitHub OIDC Identity Provider configured in AWS
An IAM role with Bedrock permissions
A GitHub App (recommended) or use the default GITHUB_TOKEN

Create a custom GitHub App (Recommended for 3P Providers)

For best control and security when using 3P providers like Vertex AI or Bedrock, we recommend creating your own GitHub App:

Go to https://github.com/settings/apps/new
Fill in the basic information:
- GitHub App name: Choose a unique name (e.g., “YourOrg Claude Assistant”)
- Homepage URL: Your organization’s website or the repository URL
Configure the app settings:
- Webhooks: Uncheck “Active” (not needed for this integration)
Set the required permissions:
- Repository permissions:
  - Contents: Read & Write
  - Issues: Read & Write
  - Pull requests: Read & Write
Click “Create GitHub App”
After creation, click “Generate a private key” and save the downloaded .pem file
Note your App ID from the app settings page
Install the app to your repository:
- From your app’s settings page, click “Install App” in the left sidebar
- Select your account or organization
- Choose “Only select repositories” and select the specific repository
- Click “Install”
Add the private key as a secret to your repository:
- Go to your repository’s Settings → Secrets and variables → Actions
- Create a new secret named APP_PRIVATE_KEY with the contents of the .pem file
Add the App ID as a secret:

Create a new secret named APP_ID with your GitHub App’s ID

This app will be used with the actions/create-github-app-token action to generate authentication tokens in your workflows.

Alternative for Anthropic API or if you don’t want to setup your own Github app: Use the official Anthropic app:

Install from: https://github.com/apps/claude
No additional configuration needed for authentication

Configure cloud provider authentication

Choose your cloud provider and set up secure authentication:

AWS Bedrock

Google Vertex AI

Add Required Secrets

Add the following secrets to your repository (Settings → Secrets and variables → Actions):

For Anthropic API (Direct):

For API Authentication:
- ANTHROPIC_API_KEY: Your Anthropic API key from console.anthropic.com
For GitHub App (if using your own app):
- APP_ID: Your GitHub App’s ID
- APP_PRIVATE_KEY: The private key (.pem) content

For Google Cloud Vertex AI

For GCP Authentication:
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
For GitHub App (if using your own app):
- APP_ID: Your GitHub App’s ID
- APP_PRIVATE_KEY: The private key (.pem) content

For AWS Bedrock

For AWS Authentication:
- AWS_ROLE_TO_ASSUME
For GitHub App (if using your own app):
- APP_ID: Your GitHub App’s ID
- APP_PRIVATE_KEY: The private key (.pem) content

Create workflow files

Create GitHub Actions workflow files that integrate with your cloud provider. The examples below show complete configurations for both AWS Bedrock and Google Vertex AI:

AWS Bedrock workflow

Prerequisites:

AWS Bedrock access enabled with Claude model permissions
GitHub configured as an OIDC identity provider in AWS
IAM role with Bedrock permissions that trusts GitHub Actions

Required GitHub secrets:

Secret Name	Description
`AWS_ROLE_TO_ASSUME`	ARN of the IAM role for Bedrock access
`APP_ID`	Your GitHub App ID (from app settings)
`APP_PRIVATE_KEY`	The private key you generated for your GitHub App

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]
  issues:
    types: [opened, assigned]

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')) ||
      (github.event_name == 'issues' && contains(github.event.issue.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-20250514-v1:0 --max-turns 10'

The model ID format for Bedrock includes the region prefix (e.g., us.anthropic.claude...) and version suffix.

Google Vertex AI workflow

Prerequisites:

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

Required GitHub 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`	Your GitHub App ID (from app settings)
`APP_PRIVATE_KEY`	The private key you generated for your GitHub App

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]
  issues:
    types: [opened, assigned]

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')) ||
      (github.event_name == 'issues' && contains(github.event.issue.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@20250514 --max-turns 10'
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5
          VERTEX_REGION_CLAUDE_3_7_SONNET: us-east5

The project ID is automatically retrieved from the Google Cloud authentication step, so you don’t need to hardcode it.

Troubleshooting

Claude not responding to @claude commands

Verify the GitHub App is installed correctly, check that workflows are enabled, ensure API key is set in repository secrets, and confirm the comment contains @claude (not /claude).

CI not running on Claude’s commits

Ensure you’re using the GitHub App or custom app (not Actions user), check workflow triggers include the necessary events, and verify app permissions include CI triggers.

Authentication errors

Confirm API key is valid and has sufficient permissions. For Bedrock/Vertex, check credentials configuration and ensure secrets are named correctly in workflows.

Advanced configuration

Action parameters

The Claude Code Action v1 uses a simplified configuration:

Parameter	Description	Required
`prompt`	Instructions for Claude (text or slash command)	No*
`claude_args`	CLI arguments passed to Claude Code	No
`anthropic_api_key`	Anthropic API key	Yes**
`github_token`	GitHub token for API access	No
`trigger_phrase`	Custom trigger phrase (default: “@claude”)	No
`use_bedrock`	Use AWS Bedrock instead of Anthropic API	No
`use_vertex`	Use Google Vertex AI instead of Anthropic API	No

*Prompt is optional - when omitted for issue/PR comments, Claude responds to trigger phrase
**Required for direct Anthropic API, not for Bedrock/Vertex

Using claude_args

The claude_args parameter accepts any Claude Code CLI arguments:

claude_args: "--max-turns 5 --model claude-sonnet-4-20250514 --mcp-config /path/to/config.json"

Common arguments:

--max-turns: Maximum conversation turns (default: 10)
--model: Model to use (e.g., claude-sonnet-4-20250514)
--mcp-config: Path to MCP configuration
--allowed-tools: Comma-separated list of allowed tools
--debug: Enable debug output

Alternative integration methods

While the /install-github-app command is the recommended approach, you can also:

Custom GitHub App: For organizations needing branded usernames or custom authentication flows. Create your own GitHub App with required permissions (contents, issues, pull requests) and use the actions/create-github-app-token action to generate tokens in your workflows.
Manual GitHub Actions: Direct workflow configuration for maximum flexibility
MCP Configuration: Dynamic loading of Model Context Protocol servers

See the Claude Code Action repository for detailed documentation.

Customizing Claude’s behavior

You can configure Claude’s behavior in two ways:

CLAUDE.md: Define coding standards, review criteria, and project-specific rules in a CLAUDE.md file at the root of your repository. Claude will follow these guidelines when creating PRs and responding to requests. Check out our Memory documentation for more details.
Custom prompts: Use the prompt parameter in the workflow file to provide workflow-specific instructions. This allows you to customize Claude’s behavior for different workflows or tasks.

Claude will follow these guidelines when creating PRs and responding to requests.

Getting started

Build with Claude Code

Claude Code SDK

Deployment

Administration

Configuration

Reference

Resources

​Why use Claude Code GitHub Actions?

​What can Claude do?

​Claude Code Action

​Setup

​Quick setup

​Manual setup

​Upgrading from Beta

​Essential changes

​Breaking Changes Reference

​Before and After Example

​Example use cases

​Basic workflow

​Using slash commands

​Custom automation with prompts

​Common use cases

​Best practices

​CLAUDE.md configuration

​Security considerations

​Optimizing performance

​CI costs

​Configuration examples

​Using with AWS Bedrock & Google Vertex AI

​Prerequisites

​For Google Cloud Vertex AI:

​For AWS Bedrock:

​For Anthropic API (Direct):

​For Google Cloud Vertex AI

​For AWS Bedrock

​Troubleshooting

​Claude not responding to @claude commands

​CI not running on Claude’s commits

​Authentication errors

​Advanced configuration

​Action parameters

​Using claude_args

​Alternative integration methods

​Customizing Claude’s behavior

Why use Claude Code GitHub Actions?

What can Claude do?

Claude Code Action

Setup

Quick setup

Manual setup

Upgrading from Beta

Essential changes

Breaking Changes Reference

Before and After Example

Example use cases

Basic workflow

Using slash commands

Custom automation with prompts

Common use cases

Best practices

CLAUDE.md configuration

Security considerations

Optimizing performance

CI costs

Configuration examples

Using with AWS Bedrock & Google Vertex AI

Prerequisites

For Google Cloud Vertex AI:

For AWS Bedrock:

For Anthropic API (Direct):

For Google Cloud Vertex AI

For AWS Bedrock

Troubleshooting

Claude not responding to @claude commands

CI not running on Claude’s commits

Authentication errors

Advanced configuration

Action parameters

Using claude_args

Alternative integration methods

Customizing Claude’s behavior