Claude Code GitHub Actions: Best CI Guide

GitHub Actions integration lets Claude Code participate in your pull requests, issues, and scheduled pipelines without leaving GitHub. Tag @claude in a comment, and Claude analyzes your diff, implements features, or posts review findings on the exact lines that changed. This guide covers workflow setup, automated code review, and self-hosted GitHub Enterprise Server differences so you can ship safer code through CI.

GitHub Actions: What You’ll Learn

GitHub Actions integration turns Claude Code into a first-class participant in your development pipeline. You will learn how to install the Claude GitHub App, author workflow YAML files, and trigger automated reviews on every pull request. By the end, you can wire GitHub Actions into any repository and let Claude catch bugs before they reach production.

Why Integrate Claude Code with GitHub

Claude Code GitHub Actions brings AI-powered automation directly into the platforms your team already uses. Instead of copying diffs into a chat window, you mention @claude inside a GitHub issue or pull request comment and Claude reads the surrounding context, your repository files, and your CLAUDE.md guidelines automatically. GitHub Actions is the bridge between your repository events and Claude’s analysis capabilities.

The GitHub Actions integration supports three broad categories of work. First, instant pull request creation: describe what you need in an issue and Claude opens a complete PR with all necessary file changes. Second, automated code implementation: turn a feature request into working code with a single comment. Third, continuous code review: a managed service posts inline findings on every pull request without any manual trigger.

This is different from Headless Mode, which focuses on one-shot, non-interactive Claude Code invocations from scripts. GitHub Actions is about event-driven CI pipelines that react to repository activity such as pushes, pull requests, and issue comments. The two complement each other: headless mode for batch scripts, GitHub Actions for live repository automation within your CI workflow.

Quick Setup: The /install-github-app Command

The fastest path to a working GitHub Actions integration is the /install-github-app command, run inside any Claude Code terminal session. This command installs the Claude GitHub App on your repository and then walks you through adding the GitHub Actions workflow files and the API key secret.

After the GitHub App is installed, the command asks whether to continue with workflow setup. In Claude Code v2.1.187 and later you can choose Skip for now to stop with only the App installed and return to the workflow and secret steps by running /install-github-app again. Earlier versions proceed straight to workflow selection.

Manual Setup: GitHub App and Secrets

If the interactive command fails or you prefer full control, manual setup takes three steps. First, install the Claude GitHub App from github.com/apps/claude to your repository. The app requests read and write permissions for Contents, Issues, and Pull requests.

Second, add your ANTHROPIC_API_KEY to the repository secrets. Navigate to Settings, then Secrets and variables, then Actions, and create a new secret with that exact name. Third, copy the example workflow file from the claude-code-action repository into your repository’s .github/workflows/ directory.

Required GitHub App Permissions

The Claude GitHub App needs three repository permissions to function correctly. Understanding each one helps you audit access during security reviews.

• Contents (read and write): Claude clones your repository to read source files and pushes branches with proposed changes.
• Issues (read and write): Claude reads issue bodies for context and posts status updates when implementing a requested feature.
• Pull requests (read and write): Claude opens new PRs, reads existing diffs, and posts inline review comments on specific lines.

Workflow YAML Anatomy

A Claude Code GitHub Actions workflow is a standard GitHub Actions YAML file that uses the anthropics/claude-code-action@v1 action. The v1 tag is the current general availability release; the older @beta tag introduced breaking changes that were resolved in the GA version. Every GitHub Actions workflow needs three things: a trigger, a job that runs on a GitHub-hosted runner, and the action step with your API key.

Basic Workflow: Responding to Comments

The most common GitHub Actions workflow listens for new issue and pull request comments. When someone types @claude in a comment, Claude reads the surrounding context and responds directly in the thread.

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

This workflow does not set a prompt input. When the prompt is omitted for issue and PR comment events, Claude automatically responds to the @claude trigger phrase. The action detects whether to run in interactive mode (responding to mentions) or automation mode (running immediately with a prompt) based on your configuration.

Triggering on Pull Requests and Issues

You can trigger Claude on pull request events directly through GitHub Actions, not just comments. This is useful for running a code review skill automatically when a PR is opened or updated. The following GitHub Actions workflow installs the code-review plugin and runs its skill on each new or synchronized pull request.

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 }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

Notice how the prompt input accepts a skill invocation, not just plain text. For a skill in your repository’s .claude/skills/ directory, run actions/checkout before the action step and pass /skill-name. For a skill packaged in a plugin, install the plugin with the plugin_marketplaces and plugins inputs and pass the namespaced /plugin-name:skill-name.

Scheduled and Push-Triggered Automation

Claude can also run on a schedule or in response to other GitHub events through GitHub Actions. A cron-triggered workflow can generate daily reports, summarize recent commits, or triage stale issues. Because there is no comment to respond to, you provide a prompt input with explicit instructions for the GitHub Actions run.

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"

The claude_args parameter passes any Claude Code CLI argument directly to the underlying invocation. Common arguments include --max-turns to cap conversation length, --model to select a specific model, and --mcp-config to load a custom Model Context Protocol server configuration file.

Action Parameters Reference

The v1 GitHub Actions action uses a simplified parameter set. Understanding each parameter helps you configure workflows precisely without reaching for the full CLI argument list.

Migrating from Beta to v1

Claude Code GitHub Actions v1.0 introduced breaking changes. If you used the beta version, you must update your GitHub Actions workflow files before upgrading. The new version simplifies configuration by removing mode configuration and unifying prompt inputs.

Four essential changes are required. First, update the action version from @beta to @v1. Second, remove the mode input entirely; the action now auto-detects whether to run in interactive or automation mode. Third, replace direct_prompt with prompt. Fourth, move CLI options like max_turns, model, and custom_instructions into the claude_args parameter.

Before and After Comparison

The beta version used separate inputs for each option, creating verbose workflow files. The GA version consolidates everything into prompt and claude_args.

# Beta version (old):
- 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-5"

# GA version (v1, current):
- 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-5

The claude_env input from beta is replaced by a settings JSON format. The allowed_tools and disallowed_tools inputs map to --allowedTools and --disallowedTools within claude_args. The --allowed-tools alias also works.

GitHub Code Review: Automated PR Analysis

Beyond the GitHub Actions action you configure yourself, Anthropic offers a managed Code Review service. This is a research preview feature available for Team and Enterprise subscriptions. It analyzes your pull requests and posts findings as inline comments on the specific lines of code where issues were found, using a fleet of specialized agents that examine changes in the context of your full codebase. Code Review works alongside your GitHub Actions workflows but runs on Anthropic infrastructure.

Each agent looks for a different class of issue: logic errors, security vulnerabilities, broken edge cases, and subtle regressions. A verification step checks candidate findings against actual code behavior to filter out false positives. Results are then deduplicated, ranked by severity, and posted as inline comments with a summary in the review body.

Severity Levels

Every finding is tagged with one of three severity levels. Understanding these helps you triage review feedback efficiently.

• Important (red): A bug that should be fixed before merging. These are production-impacting issues like incorrect logic or data leaks.
• Nit (yellow): A minor issue worth fixing but not blocking. These include style suggestions and small refactors.
• Pre-existing (purple): A bug that exists in the codebase but was not introduced by this pull request. Claude flags it for awareness without requiring action.

Findings include a collapsible extended reasoning section you can expand to understand why Claude flagged the issue and how it verified the problem. The check run always completes with a neutral conclusion, so it never blocks merging through branch protection rules. If you want to gate merges on findings, read the severity breakdown from the check run output in your own CI pipeline.

Review Trigger Modes

After an Owner enables Code Review for the organization, each repository gets its own trigger configuration. Three modes control when reviews run.

• Once after PR creation: The review runs a single time when a PR is opened or marked ready for review. This is the most cost-effective automatic mode.
• After every push: The review runs on each push to the PR branch, catching new issues as the PR evolves and auto-resolving threads when you fix flagged issues. This runs the most reviews and costs the most.
• Manual: Reviews start only when someone comments @claude review or @claude review once on a PR. Useful for high-traffic repos where you want to opt specific PRs into review.

Two manual comment commands work regardless of the configured trigger. Commenting @claude review starts a review and subscribes the PR to push-triggered reviews going forward. Commenting @claude review once starts a single review without subscribing the PR to future pushes, useful for long-running PRs with frequent pushes.

Customizing Reviews with CLAUDE.md and REVIEW.md

Code Review reads two files from your repository to guide what it flags. They differ in how strongly they influence the review, and using both gives you fine-grained control over feedback quality.

CLAUDE.md for Project Context

Your repository’s CLAUDE.md file defines shared project instructions that Claude Code uses for all tasks, not just reviews. Code Review reads it as project context and flags newly introduced violations as nit-level findings. This works bidirectionally: if your PR changes code in a way that makes a CLAUDE.md statement outdated, Claude flags that the documentation needs updating too.

Claude reads CLAUDE.md files at every level of your directory hierarchy. Rules in a subdirectory’s CLAUDE.md apply only to files under that path, letting you set different standards for different parts of a monorepo. For review-specific guidance that should not apply to general Claude Code sessions, use REVIEW.md instead.

REVIEW.md for Review-Only Rules

REVIEW.md is a file at your repository root that overrides how Code Review behaves on your repo. Its contents are injected into the system prompt of every agent in the review pipeline as the highest-priority instruction block, taking precedence over the default review guidance. Because it is pasted verbatim, @ import syntax is not expanded and referenced files are not read into the prompt.

You can tune six aspects of review behavior with REVIEW.md. Severity calibration lets you redefine what Important means for your repo, narrowing it for docs or config repositories. Nit volume caps limit how many yellow comments a single review posts, keeping prose and config file feedback actionable. Skip rules list paths and finding categories where Claude should post nothing, such as generated code or lockfiles.

Repo-specific checks add rules you want flagged on every PR, like requiring integration tests for new API routes. Verification bar settings require evidence before a class of finding is posted, cutting false positives. Re-review convergence tells Claude how to behave when a PR has already been reviewed, preventing endless style rounds on a one-line fix.

Using Amazon Bedrock or Google Cloud

For enterprise environments, you can run Claude Code GitHub Actions with your own cloud infrastructure. This gives you control over data residency and billing while maintaining the same GitHub Actions functionality. Amazon Bedrock and Google Cloud’s Agent Platform are both supported as alternative providers.

Amazon Bedrock Configuration

Bedrock requires an AWS account with Amazon Bedrock enabled, a GitHub OIDC Identity Provider configured in AWS, and an IAM role with Bedrock permissions that trusts GitHub Actions. OIDC is more secure than static access keys because credentials are temporary and automatically rotated. The workflow uses aws-actions/configure-aws-credentials@v4 to assume the role, then sets use_bedrock: "true" on the Claude action.

- 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'

The model ID format for Amazon Bedrock includes a region prefix, such as us.anthropic.claude-sonnet-4-6. Required secrets are AWS_ROLE_TO_ASSUME plus your GitHub App credentials if you use a custom app.

Google Cloud’s Agent Platform

Google Cloud requires Workload Identity Federation configured for GitHub, a service account with Vertex AI User role, and the Agent Platform API enabled. The workflow uses google-github-actions/auth@v2 to authenticate, then sets use_vertex: "true". The project ID is automatically retrieved from the authentication step, so you do not need to hardcode it.

- 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
    VERTEX_REGION_CLAUDE_4_5_SONNET: us-east5

Required secrets are GCP_WORKLOAD_IDENTITY_PROVIDER and GCP_SERVICE_ACCOUNT. Workload Identity Federation eliminates the need for downloadable service account keys, improving security over long-lived credentials.

GitHub Enterprise Server: Self-Hosted Notes

GitHub Enterprise Server (GHES) support lets your organization use Claude Code GitHub Actions with repositories hosted on your self-managed GitHub instance instead of github.com. This is available for Team and Enterprise plans. Once an Owner connects your GHES instance, developers can run web sessions and get automated code reviews without any per-repository GitHub Actions configuration.

Most Claude Code features work on GHES with full parity, including Claude Code on the web, Code Review, Claude Security, teleport sessions, plugin marketplaces, contribution metrics, and GitHub Actions. The notable exception is the GitHub MCP server, which does not work with GHES instances. Use the gh CLI configured for your GHES host instead, authenticating with gh auth login --hostname github.example.com.

Admin Setup for GHES

An Owner connects the GHES instance once through the Claude Code admin settings at claude.ai. The guided setup generates a GitHub App manifest and redirects to your GHES instance to create the app in one click. If your environment blocks the redirect flow, a manual setup path is available where you create the GitHub App yourself and enter the credentials.

The GitHub App manifest configures broader permissions than the github.com version, including Checks (read and write) for posting Code Review check runs, Actions (read) for reading CI status during auto-fix, and Repository hooks (read and write) for receiving contribution metric webhooks. The app subscribes to pull_request, issue_comment, pull_request_review_comment, pull_request_review, and check_run events.

Key Differences from github.com

Two important differences affect GitHub Actions users on GHES. First, the /install-github-app command is github.com only. On GHES, follow the admin setup flow on claude.ai instead, and adapt the example GitHub Actions workflow file manually if you want Actions workflows. Second, your GHES instance must be reachable from Anthropic infrastructure so Claude can clone repositories and post review comments. If your instance is behind a firewall, allowlist the Anthropic API IP addresses.

Plugin marketplaces hosted on GHES work with credential requirements that vary by surface. The CLI and managed settings use the machine’s existing git credentials. Organization plugin settings on claude.ai use the GitHub App from admin setup. User settings on claude.ai require each user to connect their own GitHub Enterprise account. Always use the full git URL for GHES marketplaces, since the owner/repo shorthand always resolves to github.com.

A Worked Example

Imagine a mid-size team that wants Claude to review every pull request automatically and also respond to on-demand implementation requests in issues. They start by running /install-github-app in a Claude Code terminal session, which installs the Claude GitHub App and adds the ANTHROPIC_API_KEY secret. The interactive command also copies a starter workflow into .github/workflows/claude.yml that listens for issue and PR review comments.

Next, the team creates a second workflow file for automated code review on pull requests. This workflow triggers on pull_request events with types opened and synchronize, installs the code-review plugin from the official marketplace, and runs the /code-review:code-review skill with the repository and PR number interpolated from GitHub event variables. Now every new PR gets a review within minutes, and each subsequent push triggers a fresh analysis that auto-resolves threads when issues are fixed.

The team also adds a CLAUDE.md file at the repository root documenting their coding standards, API patterns, and testing requirements. Claude reads this file during reviews and flags newly introduced violations as nits. For review-specific rules that should not affect general Claude Code sessions, they create a REVIEW.md file that caps nits at five per review, skips generated files under src/gen/, and requires integration tests for any new API route.

To control costs, the team sets --max-turns 10 in claude_args and adds a workflow-level timeout of 20 minutes. They also enable GitHub’s concurrency controls to limit parallel runs on the same PR, preventing duplicate reviews when multiple pushes arrive in quick succession. After a week of testing, they observe that the average review cost per PR falls within the documented range, and the false positive rate drops significantly thanks to the verification step that checks candidate findings against actual code behavior.

GitHub Actions: Common Mistakes to Avoid

Even with verified documentation in hand, teams hit predictable pitfalls when first wiring Claude into their pipelines. These four mistakes account for most failed integrations.

• Hardcoding API keys in workflow files: Never commit your ANTHROPIC_API_KEY directly in YAML. Always use GitHub Secrets and reference them with ${{ secrets.ANTHROPIC_API_KEY }}. A leaked key in git history is a security incident.
• Using the beta action tag after v1 release: The @beta tag has breaking changes that were resolved in GA. If you copied an old workflow, update @beta to @v1, remove mode, replace direct_prompt with prompt, and move CLI options into claude_args.
• Forgetting to install the GitHub App on new repositories: The Claude GitHub App must be installed on each repository individually. If @claude mentions produce no response, verify the app has access to the repository and that the required permissions are granted.
• Over-triggering reviews on every push without cost awareness: The After every push trigger multiplies cost by the number of pushes. For high-traffic repositories, use Manual mode or Once after PR creation, and comment @claude review once when you need a fresh look without subscribing to future pushes.

GitHub Actions: Best Practices

Follow these five practices to keep your Claude Code GitHub Actions integration secure, cost-effective, and genuinely useful for your team.

• Keep CLAUDE.md concise and focused: A long file dilutes the rules that matter most. Put general project context in CLAUDE.md and review-specific instructions in REVIEW.md, which is injected as highest priority into every review agent.
• Cap max-turns and set workflow timeouts: Use --max-turns in claude_args to prevent excessive iterations, and set a workflow-level timeout to avoid runaway jobs. Both controls protect your API spend and your GitHub Actions minutes.
• Use GitHub concurrency controls: Limit parallel runs on the same pull request to prevent duplicate reviews when multiple pushes arrive in quick succession. This also reduces redundant API token consumption.
• Review Claude suggestions before merging: Code Review posts findings with a neutral conclusion and never blocks merges. Treat the findings as advisory input, fix the Important ones, and use the severity table in the check run Details to triage efficiently.
• Rate findings with the reaction buttons: Each review comment arrives with thumbs up and thumbs down already attached. Click the appropriate button so Anthropic can tune the reviewer. Reactions are collected after the PR merges and do not trigger re-reviews.

CI Costs and Optimization

Two cost dimensions apply when using Claude Code GitHub Actions. GitHub Actions costs come from runner minutes consumed on GitHub-hosted runners. API costs come from token usage during each Claude interaction, varying by task complexity and codebase size. Code Review averages between fifteen and twenty-five dollars per review, billed separately through usage credits and not counted against your plan’s included usage.

The review trigger you choose has the largest impact on total cost. Once after PR creation runs once per PR. After every push runs on each push, multiplying cost. Manual mode runs nothing until someone comments. In any mode, commenting @claude review opts the PR into push-triggered reviews, so additional cost accrues per push after that comment. To set a monthly spend cap, configure the limit for the Claude Code Review service in admin settings.

GitHub Actions: Frequently Asked Questions

What is the difference between GitHub Actions and Headless Mode?

GitHub Actions is event-driven CI automation that reacts to repository activity like pull requests and pushes. Headless Mode is for one-shot, non-interactive Claude Code invocations from scripts. They complement each other in a CI pipeline.

How do I trigger Claude in a pull request comment?

Type @claude followed by your request in any issue or PR comment. The action listens for issue_comment and pull_request_review_comment events with the created type, then responds automatically in the thread.

Does Code Review block my pull request from merging?

No. The check run always completes with a neutral conclusion, so it never blocks merges through branch protection rules. Findings are advisory. To gate merges, parse the severity counts from the check run output in your own CI.

Can I use Claude Code GitHub Actions with GitHub Enterprise Server?

Yes, with manual workflow setup. The /install-github-app quickstart is github.com only. On GHES, an Owner connects the instance through admin settings, and you adapt the example workflow file manually for Actions.

How much does Code Review cost per pull request?

Each review averages fifteen to twenty-five dollars, billed separately through usage credits. Cost scales with PR size and codebase complexity. Manual trigger mode costs nothing until someone comments @claude review on a PR.

These answers cover the most common questions teams raise during setup. If your scenario involves a cloud provider or a self-hosted runner, consult the official documentation linked throughout this guide.

GitHub Actions integration brings Claude Code directly into your pull request and issue workflows, combining on-demand implementation with managed code review. Start with /install-github-app, add your API key secret, and choose a trigger mode that balances coverage with cost.