Guides

Claude Code GitHub Actions setup: @claude in issues and PRs

Published October 30, 2026 · Last checked October 30, 2026

Claude Code GitHub Actions is a GitHub Action that runs Claude Code inside your repository's workflows: mention @claude in a pull request or issue comment and Claude analyzes code, implements changes and pushes commits. This page is the step-by-step: quick setup and manual setup, the basic workflow, the common inputs, who can trigger a run, cost and security notes, and what to check when it does not respond. It follows Anthropic's Claude Code GitHub Actions, checked against that page on October 30, 2026.

What it does

The Claude Code GitHub Action runs Claude Code inside your repository's workflows. Mention @claude in a pull request or issue comment to have Claude analyze code, implement changes and push commits. You can also give it a prompt to run automatically on any GitHub event. Anthropic lists these uses: turn issues into pull requests, fix bugs from a comment, and automate recurring tasks.

Several products share the Claude Code name. This page covers claude-code-action, which you configure with workflow files in your repository. If you want automatic review on every pull request without writing a workflow, Anthropic's page points to a separate product, Code Review.

Setup: quick or manual

For either path you need admin access to the repository.

Quick setup

/install-github-app works only with github.com repositories. If your repository's git remote is on gitlab.com or bitbucket.org, the command prints a notice and exits instead of starting setup.

1. Install the GitHub CLI and authenticate it with gh auth login. Claude Code checks for it and warns you if it is missing.
2. Open claude in the repository you want to connect, run /install-github-app and follow the prompts. Claude Code installs the Claude GitHub App, then sets up an authentication secret for the workflows.
3. How the secret is chosen: 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 you choose between creating a long-lived token with your Claude subscription and pasting in an API key.
4. Claude Code saves the credential as a repository secret, named ANTHROPIC_API_KEY for an API key or CLAUDE_CODE_OAUTH_TOKEN for a subscription token.
5. Claude Code pushes a branch with the workflow files you select, already set to use that secret, and opens GitHub in your browser with a pull request ready to create. Create and merge that pull request, and @claude works in the repository.

To stop partway, press Esc. A step already in progress finishes, and no later step starts. The closing message lists what already happened in the repository, such as a pushed branch or a saved secret. After installing the GitHub App, Claude Code asks whether to continue with GitHub Actions setup. Choose Skip for now to stop with only the GitHub App installed, and run /install-github-app again later to finish the workflow and secret steps.

If you select the review workflow, Claude posts each review on the pull request itself, as an inline comment on each issue it finds or as one summary comment when it finds none. Claude skips some pull requests, such as drafts. Before v2.1.229, Claude wrote its review only to the workflow run log.

To update a review workflow that an earlier version generated, do one of the following:

• Run /install-github-app again. When the repository already has a claude.yml, select Update workflow file with latest version. Claude Code pushes fresh copies of the workflow files to a new branch and opens the pull request, the same as a first install.
• Add the --comment argument and the claude_args line from the review workflow example below to the checked-in file yourself, which keeps any other edits you made to it.

If you use Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, Anthropic's page sends you to a separate one: Use Claude Code GitHub Actions with cloud providers.

Manual setup

1. Install the Claude GitHub App. Install the Claude GitHub App to your repository. The action relies on three of the app's permissions:

• Contents: read and write, so Claude can modify repository files.
• Issues: read and write, so Claude can respond to issues.
• Pull requests: read and write, so Claude can create PRs and push changes.

During installation you also grant permissions that other Claude features use; the full set is under "GitHub App permissions" below.

2. Add an authentication secret. Add one of the following secrets to your repository, depending on how you authenticate. GitHub's guide is using secrets in GitHub Actions.

• ANTHROPIC_API_KEY: a Claude API key from the Claude Console.
• CLAUDE_CODE_OAUTH_TOKEN: an OAuth token that authenticates with your Claude subscription, available on Pro, Max, Team and Enterprise plans. Generate one by running claude setup-token locally.

In workflow files, pass the secret to the matching input: anthropic_api_key for an API key, or claude_code_oauth_token for an OAuth token.

3. Copy the workflow file. Copy examples/claude.yml into your repository's .github/workflows/ directory. The file is a working workflow, not just an example. As committed, Claude responds whenever someone mentions @claude in an issue or pull request, authenticating with the ANTHROPIC_API_KEY secret. If you added CLAUDE_CODE_OAUTH_TOKEN instead, change the workflow's anthropic_api_key line to claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

After setup, test it by tagging @claude in an issue or PR comment.

Setting up an organization

Quick setup and manual setup configure one repository at a time. To roll the action out across 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 action, or define the job once as a reusable workflow that each repository calls.

For a secret shared across repositories, authenticate with an API key from the Claude Console rather than an OAuth token, since an OAuth token is tied to the subscription of the person who ran claude setup-token. To avoid storing a long-lived secret entirely, use workload identity federation: the action exchanges the workflow's GitHub OIDC token for Claude API access through a Claude Console service account. The inputs are anthropic_federation_rule_id, anthropic_organization_id, and the optional anthropic_service_account_id and anthropic_workspace_id, and the workflow needs the id-token: write permission. The Console-side configuration is in the action's setup guide.

GitHub App permissions

The Claude GitHub App is shared by every Claude feature that integrates with GitHub, including this action, Code Review and auto-fix for pull requests in cloud sessions. A GitHub App has a single permission set, so it includes some permissions the action doesn't use. When you install the app, you grant:

Installing the app means accepting its full permission set; GitHub doesn't let you accept a subset. If your organization requires only the permissions the action uses, create a custom GitHub App with Contents, Issues and Pull requests, following the action's setup guide. A custom app covers only this action. Code Review and web auto-fix still require the official app.

The basic workflow: respond to @claude

This workflow runs the action in interactive mode, so Claude responds whenever someone mentions @claude in an issue or PR comment.

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

The parts of this workflow that aren't boilerplate:

• id-token: write: required for the 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 action also checks the trigger phrase itself before responding.

Once the workflow is in place, mention @claude in any issue or PR comment with a request:

@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 replies in a comment on the same issue or PR and updates it as it works.

Interactive mode, automation mode and who can trigger a run

The action detects how to run from your workflow configuration:

• 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 checks below. By default, results appear in the workflow run log rather than a comment. Claude can post to the issue or pull request when the prompt directs it to and it has a tool that can post.

In both modes, the action runs two checks on the triggering actor before Claude starts, and the run fails when either check rejects it:

• 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 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.

Common inputs

These are the most commonly used inputs. Each maps to a with: key in the anthropics/claude-code-action step.

For the full input list, see the action's configuration reference.

Passing CLI arguments with claude_args

The claude_args parameter accepts any Claude Code CLI argument:

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

Common arguments:

• --max-turns: limit the number of conversation turns.
• --model: model to use, for example claude-sonnet-5. Without this argument, the 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.

More example workflows

The examples directory contains ready-to-use workflows for different scenarios. The examples on this page show API key authentication. If you authenticate with a Claude subscription, replace the anthropic_api_key line in any example with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Review pull requests automatically (run a skill)

The prompt input accepts a skill invocation as well as plain text:

• 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.

The following workflow installs the code-review plugin and runs its skill when a pull request is opened, updated, reopened, or marked ready for review. It runs the same plugin as the review workflow from quick setup. Use a workflow like this when you want to control the prompt, model and triggers yourself. On public repositories, GitHub withholds secrets from runs triggered by fork pull requests, so the review runs only on pull requests from branches in the same repository.

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
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-plugins-official.git"
          plugins: "code-review@claude-plugins-official"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Two lines in this workflow control where the review goes:

• --comment: Claude posts its review on the pull request, as an inline comment on each issue it finds or as one summary comment when it finds none. Without it, Claude posts nothing, and you read the findings in the workflow run log.
• claude_args: keep this line even though the skill's own allowed-tools frontmatter names the same tool, because the action starts the MCP server that posts inline comments only when --allowedTools in claude_args names it.

Claude skips draft and closed pull requests, pull requests it judges not to need a review, such as automated or trivial ones, and pull requests that already have a comment from Claude.

Run on a schedule

With a prompt input, the action runs in automation mode on any GitHub event, including a cron schedule. For a plain-text prompt, Claude has no shell or GitHub API access until you grant the tools the prompt needs, with --allowedTools in claude_args or a permissions.allow rule in the settings input. If you invoke a skill instead, Claude can use the tools its allowed-tools frontmatter grants. GitHub runs scheduled workflows only from the default branch and, in public repositories, disables the schedule after 60 days without repository activity.

This workflow generates a report in the workflow run log at 09:00 UTC each day. Its claude_args line selects the model and allows two GitHub MCP tools. Claude reads commits and issues through the GitHub API with those tools, so you can omit the checkout step:

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-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

Define project standards in CLAUDE.md

Create a CLAUDE.md file in your repository root to define code style guidelines, review criteria, project-specific rules and preferred patterns. Claude follows these guidelines when creating PRs and responding to requests. How to write one is covered in CLAUDE.md setup.

Security: credentials and permissions

Warning: never commit API keys or OAuth tokens directly to your repository. Always store them as GitHub Secrets and reference them in workflows, for example anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}.

• Grant the workflow only the permissions it needs, and review Claude's changes before merging.
• To authenticate without storing a long-lived secret, use the workload identity federation described above.
• Deleting a secret does not invalidate the credential it held. To retire an API key entirely, also delete the key in the Claude Console.
• For security guidance including permissions and authentication, see the Claude Code Action security documentation. For data handling and retention, Anthropic points to its data usage and security pages.

For the Claude Code mechanisms that control what the tool may do, see permission modes and hooks.

Cost and usage

Each run consumes two kinds of resources:

• GitHub Actions minutes: the 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.

You can lower both kinds of cost by giving Claude clearer context and by capping how much work each run can do:

• 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.

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 the exceptions under "who can trigger a run" above.

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 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 troubleshooting section of the cloud provider page.

For more solutions, see the action's FAQ.

Uninstalling and upgrading from beta

• 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.
• 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.
• 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.
• If your workflows still reference anthropics/claude-code-action@beta, update them to v1: change @beta to @v1 in the uses line; remove the mode input, since the action now detects the mode automatically; replace direct_prompt with prompt; and move CLI options such as max_turns and model into claude_args.

FAQ

Sources

• Claude Code GitHub Actions (setup, workflow examples, inputs, permissions, costs, troubleshooting; checked October 30, 2026)