Claude Code + GitHub Actions: setup guide

Claude Code GitHub Actions brings @claude mentions to your PRs and issues — Claude can analyze code, implement features, fix bugs, and open pull requests while following your project's CLAUDE.md. It's built on the Claude Agent SDK, so the same action also powers custom scheduled and event-driven automation.

Why use it

Quick setup

Run /install-github-app in the Claude Code terminal. It installs the Claude GitHub App on your repository, then asks whether to continue setting up GitHub Actions — on v2.1.187+ you can choose "Skip for now" and return to the workflow/secret steps later by running the command again. You must be a repository admin, and the GitHub App requests read & write on Contents, Issues and Pull requests. This quickstart is for direct Claude API users only — see the cloud-provider section below for Bedrock or Vertex.

Manual setup

If the quickstart command fails, or you prefer to do it by hand: (1) install the Claude GitHub app at github.com/apps/claude with Contents/Issues/Pull requests read & write; (2) add ANTHROPIC_API_KEY as a repository secret; (3) copy examples/claude.yml from the claude-code-action repo into .github/workflows/. Test it by tagging @claude in any issue or PR comment.

A minimal 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

Upgrading from the beta action

v1.0 is a breaking change. Update: change @beta to @v1, delete mode, rename direct_prompt to prompt, and move CLI-style options into claude_args.

What to type

• @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
• Run a code-review skill/plugin on every new or updated pull request
• Trigger a scheduled prompt (e.g. a daily digest of merged PRs and open issues)

Invoking a skill from the prompt

The prompt input accepts a skill invocation instead of plain text. For a skill in .claude/skills/, checkout the repo first, then pass /skill-name. For a skill packaged in a plugin, install it with plugin_marketplaces and plugins, then pass the namespaced /plugin-name:skill-name.

- 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 }}"

Costs to plan for

Using Amazon Bedrock or Google Cloud instead of the API

For enterprise environments you can route through your own cloud infrastructure instead of the direct Claude API — this gives you control over data residency and billing. It requires enabling the model in Bedrock or Google Cloud's Agent Platform, configuring GitHub OIDC (no long-lived cloud keys), and — recommended for both providers — creating your own GitHub App instead of using the shared Anthropic one. Set use_bedrock: "true" or use_vertex: "true" in the action and pass AWS_ROLE_TO_ASSUME or GCP_WORKLOAD_IDENTITY_PROVIDER / GCP_SERVICE_ACCOUNT as secrets.

Advanced configuration: action parameters

The v1.0 action simplifies configuration into a small set of top-level inputs, with everything CLI-specific passed through claude_args.

Best practices that keep it useful

Create a CLAUDE.md at the repository root defining code style, review criteria and project-specific rules — this is what shapes every PR and response Claude produces from the action, the same way it shapes an interactive session. For performance, use issue templates so Claude starts with real context instead of guessing, keep CLAUDE.md concise and focused rather than exhaustive, and set workflow-level timeouts so a stuck run doesn't burn Actions minutes indefinitely.

Scheduled and fully custom workflows

The action isn't limited to responding to @claude comments — pass a prompt directly with any GitHub trigger, including cron, to run unattended automation. A daily report workflow, for example, needs no human mention at all: it fires on a schedule, gives Claude a standing instruction, and posts the result wherever your workflow sends it.

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"

Custom GitHub App for branded commits

The official Anthropic app is the fastest path and needs no extra configuration, but organizations that want commits and PRs to carry their own bot identity — rather than "Claude" — create a dedicated GitHub App instead: set Contents, Issues and Pull requests to Read & Write, generate a private key, install it on the target repository, and store the App ID and private key as APP_ID and APP_PRIVATE_KEY secrets. The actions/create-github-app-token action then exchanges those for a short-lived token each run, which is also the recommended pattern when authenticating through Bedrock or Vertex.

Permissions the workflow itself needs

Beyond the GitHub App's repository permissions, the workflow file needs its own permissions block when Claude is expected to push commits, comment, or open pull requests — typically contents: write, pull-requests: write and issues: write, plus id-token: write if you're authenticating to Bedrock or Vertex via OIDC. Missing one of these shows up as a silent failure where Claude responds in the log but the resulting commit, comment or PR never appears, which is a common first debugging step before checking secrets or the GitHub App installation itself.

Troubleshooting

FAQ