Claude Code GitHub Actions

• Code Review: automatic review on every pull request, without writing a workflow
• Claude Code on the web: Claude Code sessions from your browser or phone
• Claude Agent SDK: custom automation outside GitHub Actions. The Claude Code GitHub Action is built on the SDK
• GitHub Enterprise Server: Claude Code with self-hosted GitHub

​

Setup

• Quick setup: run /install-github-app from Claude Code. Claude Code installs the GitHub App, adds your authentication secret, and prepares the workflow pull request for you
• Manual setup: install the app, add the secret, and copy the workflow file into your repository yourself. Use this path when you don’t run Claude Code locally, when the command fails, or when you want full control of the workflow files

​

Quick setup

• If Claude Code already has an API key, it reuses that key, and offers to keep the repository’s existing ANTHROPIC_API_KEY secret if one is already set
• Otherwise, choose between creating a long-lived token with your Claude subscription and pasting in an API key

​

Manual setup

​

Set up for an organization

• Install the Claude GitHub App once at the organization level, choosing all repositories or a selected list
• Store the authentication secret as an organization-level Actions secret so each repository doesn’t need its own copy
• Add the workflow file to each repository that should run the Claude Code GitHub Action, or define the job once as a reusable workflow that each repository calls

• anthropic_federation_rule_id: the federation rule ID, fdrl_...
• anthropic_organization_id: your Anthropic organization ID
• anthropic_service_account_id: the service account ID, svac_.... Optional, since the federation rule you create in the Console already targets a service account
• anthropic_workspace_id: the workspace ID, wrkspc_.... Optional when the federation rule targets a single workspace

​

Uninstall

• Workflow files: delete the workflows that use anthropics/claude-code-action from .github/workflows/. If you used quick setup, look for claude.yml and, if you selected the review workflow, claude-code-review.yml. With the workflows deleted, the Claude Code GitHub Action no longer runs
• Secrets: delete the ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN secret from the repository, and from organization-level Actions secrets if you shared it across repositories. If you delete a secret, the credential it held stays valid. To retire an API key entirely, also delete the key in the Claude Console
• GitHub App: uninstall the Claude GitHub App in your repository or organization settings under GitHub Apps, but only if you don’t use it for another Claude feature, such as Code Review or web auto-fix

​

GitHub App permissions

​

Interactive and automation modes

• Interactive mode: when the workflow provides no prompt input, Claude waits for the trigger phrase, @claude by default, in an issue or pull request comment, in a pull request review, or in the body or title of a newly opened issue, then responds to that request. Progress and results appear as a comment on the triggering issue or PR.
• Automation mode: when the workflow provides a prompt input, Claude runs without waiting for a mention, subject only to the access checks below. Results appear in the workflow run log rather than a comment.

​

Who can trigger runs

• Write access: on issue and pull request events, the triggering user must have write access to the repository. To allow specific users without write access, set allowed_non_write_users and pass your own github_token input. Events that no user authors, such as a schedule trigger, skip this check.
• Human actor: on every event, the Claude Code GitHub Action rejects a bot actor unless you list it in allowed_bots, which keeps bots from triggering Claude in a loop. This check also applies to scheduled runs, which GitHub attributes to a repository user, usually the one who last changed the workflow’s cron schedule. If that user is a bot, list it in allowed_bots.

​

Example use cases

​

Respond to @claude mentions

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

• id-token: write: required for the Claude Code GitHub Action’s default GitHub App authentication
• actions: read: lets Claude read CI results on PRs
• actions/checkout: gives Claude a local copy of the repository to work in
• if: keeps runners from starting on comments that don’t mention @claude. The Claude Code GitHub Action also checks the trigger phrase itself before responding

@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 skill

• For a skill in your repository’s .claude/skills/ directory, run actions/checkout before the anthropics/claude-code-action step so the skill files are available on the runner, then pass /skill-name as the prompt.
• For a skill packaged in a plugin, install the plugin with the plugin_marketplaces and plugins inputs, then pass the namespaced /plugin-name:skill-name as the prompt. The plugins input takes plugin-name@marketplace-name, where the marketplace name comes from the marketplace’s own manifest rather than its repository URL.

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - 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 }}"

​

Run on a schedule

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    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-8
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

​

Best practices

​

Define project standards in CLAUDE.md

​

Protect your credentials

​

Manage costs

• GitHub Actions minutes: the Claude Code GitHub Action runs on GitHub-hosted runners, which consume your GitHub Actions minutes. See GitHub’s billing documentation for pricing and minute limits.
• API tokens: each interaction consumes tokens based on the length of prompts and responses, task complexity, and codebase size. See Claude’s pricing page for current token rates. If you authenticate with an OAuth token, runs use your Claude subscription instead of API billing.

• Write specific @claude requests so Claude needs fewer turns to finish
• Use issue templates to provide context up front
• Keep your CLAUDE.md concise, since Claude reads it on every run
• Set --max-turns in claude_args to limit iterations
• Set workflow-level timeouts to avoid runaway jobs
• Use GitHub’s concurrency controls to limit parallel runs

​

Use a cloud provider

• Amazon Bedrock: use_bedrock: "true"
• Google Cloud’s Agent Platform: use_vertex: "true"
• Microsoft Foundry: use_foundry: "true"

​

Troubleshooting

​

Claude not responding to @claude commands

• Verify the GitHub App is installed on the repository
• Check that workflows are enabled for the repository
• Ensure your API key or OAuth token is set in repository secrets
• Confirm the comment contains @claude as a complete word, not /claude or @claude-bot
• Confirm the commenting user has write access to the repository. See Who can trigger runs for the exceptions

​

CI not running on Claude’s commits

• GitHub doesn’t trigger workflows on commits made with the default GITHUB_TOKEN. If you pass github_token: ${{ secrets.GITHUB_TOKEN }} to the Claude Code GitHub Action, remove it so it authenticates as the Claude GitHub App, or pass a custom app token instead
• Check that your CI workflow’s triggers include the events Claude’s pushes produce, such as push or pull_request

​

Authentication errors

• Confirm the API key or OAuth token is valid by testing it locally with claude before debugging the workflow
• For Bedrock, Agent Platform, and Foundry, see the cloud provider page’s troubleshooting section

​

Advanced configuration

​

Action parameters

​

Pass CLI arguments

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

• --max-turns: limit the number of conversation turns
• --model: model to use, for example claude-sonnet-5. Without this argument, the Claude Code GitHub Action uses the Claude Code default model
• --mcp-config: path to MCP configuration
• --allowedTools: comma-separated list of allowed tools. The --allowed-tools alias also works
• --debug: enable debug output

​

Upgrade from beta

1. Change @beta to @v1 in the uses line
2. Remove the mode input, since the Claude Code GitHub Action now detects the mode automatically
3. Replace direct_prompt with prompt
4. Move CLI options such as max_turns and model into claude_args. custom_instructions has no same-name flag and becomes --append-system-prompt

​

What’s next

• Use Claude Code GitHub Actions with cloud providers: route inference through Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry
• Configuration reference: the full list of action inputs
• Examples directory: ready-to-use workflows for more scenarios
• Code Review: automatic pull request review without maintaining a workflow file