Claude Code GitHub Actions: Setup, @claude Mentions and Automatic PR Review

Claude Code GitHub Actions: Setup, @claude Mentions and Automatic PR Review

The first time you tag @claude on a GitHub issue and watch a pull request show up twenty minutes later, it feels a little like cheating. You wrote two sentences. Something read the repo, made a branch, ran the checks and left a comment explaining what it did.

Then the second feeling arrives. Who exactly is allowed to trigger that? What is it allowed to touch? And what does each of those twenty minutes cost?

This guide covers the Claude Code GitHub integration end to end: the one-command setup, the manual setup, the @claude workflow, an automatic pull request review workflow, the difference between the open-source action and the managed Code Review product, how to cap the bill, and the security settings I would not skip. I checked it against Anthropic's documentation on October 29, 2026. The action and the app change fast, so where this page and the docs disagree, trust the docs. Sources are at the bottom.

What "Claude Code GitHub" Actually Means

Claude Code GitHub Actions is a GitHub Action, anthropics/claude-code-action, that runs Claude Code inside your repository's workflows. It responds to @claude mentions and can also run a prompt automatically on any GitHub event.

The confusing part is that several things share the Claude Code name on GitHub. The docs say this outright, and it is worth getting straight before you configure anything:

• The GitHub Action (this guide). You add workflow files to the repo, and the job runs on your GitHub runners with your credentials.
• Code Review. A managed service that reviews every pull request on Anthropic infrastructure. No workflow file. It is for Team and Enterprise plans.
• The /code-review command. You run it inside a local Claude Code session on your own branch. Any plan.
• Claude Code in the cloud. Sessions that run on cloud infrastructure instead of your laptop, including auto-fix for pull requests.
• The Agent SDK. The action is built on it. You use it directly when you want automation outside GitHub.

If your goal is "tag Claude in an issue and get a PR", you want the action. If your goal is "every PR gets a review without anyone maintaining YAML", look at Code Review, which I cover further down. If you only want a review of your own branch before you push, the local command is enough.

Everything below is the action unless I say otherwise.

Quick Setup With /install-github-app

The fastest path is one slash command. You need admin access to the repository, and the GitHub CLI installed and authenticated with gh auth login. Claude Code checks for gh and warns you if it is missing.

cd your-repo
claude

Then inside the session:

/install-github-app

Follow the prompts. Claude Code does four things for you:

1. Installs the Claude GitHub App on the repository.
2. Sets up an authentication secret. If Claude Code already has an API key it reuses it and offers to keep an existing ANTHROPIC_API_KEY secret. Otherwise you pick between creating a long-lived token tied to your Claude subscription or pasting an API key.
3. Saves the credential as a repository secret, named ANTHROPIC_API_KEY for a key or CLAUDE_CODE_OAUTH_TOKEN for a subscription token.
4. Pushes a branch with the workflow files you selected, already wired to that secret, and opens GitHub in your browser with a pull request ready to create.

Merge that pull request and @claude works in the repo. That is the whole setup.

A few details from the docs that save you time:

• github.com only. If your remote is on GitLab or Bitbucket, the command prints a notice and exits. GitLab has its own CI/CD integration.
• You can bail out. Press Esc to stop partway. A step already running finishes, nothing later starts, and the closing message lists what already happened, such as a pushed branch or a saved secret.
• You can install the app now and finish later. Choose "Skip for now" after the app install, then run /install-github-app again when you are ready for the workflow and secret.
• It can update old workflows. If the repo already has a claude.yml, rerun the command and choose "Update workflow file with latest version". It opens a fresh PR with the new files.
• The review workflow is optional. If you select it during setup, Claude posts each review on the PR as inline comments, or one summary comment when it finds nothing. Before v2.1.229 it wrote reviews only to the workflow run log, so if your review workflow was generated earlier, update it.

Quick setup works with the Claude API and Claude subscriptions. If you run Claude Code through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, the setup is different and covered in the cloud providers section below.

Manual Setup: App, Secret, Workflow File

Use the manual path when you do not run Claude Code locally, when the command fails, or when you want full control of the files.

1. Install the Claude GitHub App. Install it on the repository. The action relies on three of its permissions: Contents (read and write), Issues (read and write) and Pull requests (read and write).

2. Add a secret. Add one of these as a repository secret:

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

In workflow files, the API key goes to the anthropic_api_key input and the token goes to claude_code_oauth_token.

3. Copy the workflow. Take examples/claude.yml from the action's repository into .github/workflows/. As committed it responds to @claude mentions using ANTHROPIC_API_KEY. If you use the OAuth token instead, change that one line to claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Test it by tagging @claude in an issue or PR comment.

API Key or Subscription Token?

This is the choice people get wrong, so here is how I would decide:

• Solo repo, personal project: the subscription token is fine. Runs use your subscription instead of API billing, which means they also count against your allowance. If you have ever hit the wall, read how Claude Code usage limits work before you let a bot spend it for you on every PR.
• Team repo or organization: use an API key. The docs make the point directly: an OAuth token is tied to the subscription of the person who ran claude setup-token. When that person leaves or changes plan, every repo using their token breaks, and their personal allowance is what is paying for the team's reviews.
• No long-lived secret at all: use workload identity federation. The action exchanges the workflow's GitHub OIDC token for API access through a Claude Console service account. You set anthropic_federation_rule_id and anthropic_organization_id, optionally the service account and workspace IDs, and grant the job id-token: write.

The @claude Workflow, Line by Line

Here is the workflow from the docs for responding to 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 }}

The parts that are not boilerplate:

• id-token: write is required for the action's default GitHub App authentication.
• actions: read lets Claude read CI results on pull requests. That is how it can say "the tests failed on this line" instead of guessing.
• actions/checkout gives Claude a local copy of the repo to work in.
• if: contains(...) keeps runners from starting on comments that do not mention @claude. The action also checks the trigger phrase itself, but the if saves you a runner spin-up on every unrelated comment.

Once it is merged, you talk to it in plain language:

@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 that comment as it works. The trigger phrase is @claude by default and can be changed with trigger_phrase.

One thing the docs state that is easy to miss: the comment must contain @claude as a complete word. /claude and @claude-bot do not count.

What Makes a Good @claude Request

The action is only as good as the instruction. The cost section below says the same thing from the money side: specific requests need fewer turns. Three habits that help:

• Point at files and symptoms. "Fix the TypeError in UserDashboard.tsx when user.profile is null" beats "fix the dashboard bug".
• Say what done looks like. "Add a test that fails before the fix" gives it a finish line.
• Ask questions first when the design is open. @claude how would you approach this? costs less than a branch you throw away. It is the same logic as plan mode: decide before you build.

Interactive Mode vs Automation Mode

The action picks its mode from your workflow, with no mode input to set.

• Interactive mode. No prompt input. Claude waits for the trigger phrase in an issue comment, a PR comment, a PR review, or the title or body of a newly opened issue, then responds. Progress and results show up as a comment.
• Automation mode. You provide a prompt. Claude runs on whatever event triggers the workflow, without anyone mentioning it. By default the output goes to the workflow run log, not a comment. It can post to the issue or PR only when your prompt tells it to and it has a tool that can post.

That second point trips people up. You set up an automatic reviewer, the job goes green, and nothing appears on the pull request. The review is in the run log. Posting is opt-in, and the next section shows how.

Automatic Pull Request Review

This is the workflow most teams actually want. It runs on every pull request and posts a review. The docs example uses the official code-review plugin:

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 decide where the review goes:

• --comment makes Claude post the review on the PR, as an inline comment on each issue or one summary comment when it finds none. Leave it off and nothing is posted.
• claude_args with --allowedTools has to stay, even though the skill names the same tool in its own frontmatter. The action only starts the MCP server that posts inline comments when --allowedTools in claude_args names it.

Notice the permissions. This job gets contents: read and pull-requests: read, not write. A reviewer does not need to push code. Giving it less is free and removes a whole class of surprises.

What it skips, per the docs: draft and closed pull requests, pull requests it judges not to need a review (automated or trivial ones), and pull requests that already have a comment from Claude.

Two practical limits:

• Fork PRs on public repos. GitHub withholds secrets from runs triggered by fork pull requests, so this review only runs on PRs from branches in the same repository.
• It is not a merge gate. Treat the output as a second reader, not an approver. My own take is that it should never be the only review on code that touches auth, billing or data deletion. The pull request manifest I wrote about earlier is a better way to make agent-written PRs checkable by a human, whichever tool wrote them.

You are not locked into the plugin either. The prompt input accepts plain text or a skill invocation. For a skill that lives in your repo's .claude/skills/ directory, run actions/checkout first and pass /skill-name as the prompt. If you want to write your own review skill with your team's rules in it, writing a Claude Code skill walks through the format.

Claude Code Action vs Managed Code Review

There are two ways to get automatic reviews on GitHub, and they are different products. This table is the short version:

How the managed product works, per the docs: several agents read each change alongside the surrounding code, a verification step checks the findings against the code to filter false positives, the rest are deduplicated and ranked by severity, and the results land as inline comments, a summary and a check run called Claude Code Review. The check run does not conclude as a failure, and a review never approves or blocks the PR. There are three review levels, Quick, Standard (the default) and Deep, and more thorough means more cost.

It is not available to organizations with Zero Data Retention enabled or with the HIPAA configuration applied, and a review works only by reading the diff and the surrounding code. It does not build or run your code.

My rule of thumb: if you are on Team or Enterprise and the only thing you want is reviews, use the managed product and delete the YAML you would otherwise maintain. If you want Claude to also take tickets, fix CI or run scheduled jobs, you need the action anyway, and you can run both. For a wider look at the review tool market, see the AI code review tools comparison.

Teach It Your Standards With CLAUDE.md

Claude reads your CLAUDE.md on every run. That makes it the cheapest lever you have over review quality. Put in the things a human reviewer on your team would say out loud: code style rules, what counts as a blocker, patterns to prefer, directories nobody should touch.

Two cautions from the docs and from common sense:

• Keep it short. The docs list a concise CLAUDE.md as a cost saver precisely because it is read on every run. A 600-line file is a token tax on every pull request.
• Move workflow detail into skills. Rules about how to do a task belong in a skill that loads on demand. Rules about what the project is belong in CLAUDE.md.

For the managed Code Review product, REVIEW.md is read from the base or default branch and never from the pull request's own changes. That detail matters: it means a contributor cannot edit the review instructions inside the PR they want reviewed.

Run Claude on a Schedule

With a prompt and a schedule trigger, the action becomes a cron job that can think. The docs example generates a daily report of commits and open issues:

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"

Things to know before you rely on it:

• No tools by default for a plain-text prompt. Claude has no shell or GitHub API access until you grant tools with --allowedTools or a permissions.allow rule in the settings input. A skill invocation can use the tools its own frontmatter grants.
• Default branch only. GitHub runs scheduled workflows only from the default branch.
• 60-day shutoff on public repos. GitHub disables the schedule after 60 days without repository activity.
• Output goes to the run log unless you tell it to post somewhere.
• The actor check still applies. GitHub attributes scheduled runs to a repository user, usually the one who last changed the cron line. If that user is a bot, list it in allowed_bots.

Good scheduled jobs are boring ones: a weekly dependency report, a stale-issue triage summary, a changelog draft. Anything that mutates the repo on a timer deserves a second look.

Who Can Trigger It, and What It Can Touch

This is the part to read twice. You are letting text typed into a GitHub comment start a process that has write access to your code and a billable credential. The action has guardrails, and you should know exactly what they are.

Two checks run before Claude starts. The run fails if either rejects the actor:

• Write access. On issue and pull request events, the triggering user must have write access to the repo. To allow specific users without it, set allowed_non_write_users and pass your own github_token.
• Human actor. On every event, a bot actor is rejected unless it is in allowed_bots. This is what stops bots from triggering Claude in a loop.

The app has a wide permission set. This surprised me when I first read it. The Claude GitHub App is shared by every Claude feature that integrates with GitHub, so installing it grants Actions, Checks, Contents, Discussions, Issues, Pull requests, Workflows and Repository hooks at read and write, plus Administration, Members, Merge queues, Metadata and Statuses at read. GitHub does not let you accept a subset. If your organization only allows what the action itself needs (Contents, Issues, Pull requests), the docs say to create a custom GitHub App with just those. Note that a custom app covers only the action. Code Review and web auto-fix still need the official app.

What I would do on top of the defaults:

• Give every job the minimum permissions block. The review workflow above is read-only on purpose. Only the @claude workflow needs write.
• Treat issue and PR text as untrusted input. Anyone who can comment can put instructions in front of the model. The write-access check limits who that is, but a repo with many collaborators still has many people who can steer it. This is my reasoning, not a quote from the docs: assume a hostile sentence will eventually reach the prompt, and make sure the damage is bounded by the token's permissions and --allowedTools. The least-privilege guide for coding agents goes deeper on that thinking.
• Never put a key in the repo. Secrets only, referenced as ${{ secrets.ANTHROPIC_API_KEY }}. The docs repeat this one for a reason.
• Review everything before merging. Branch protection should still require a human approval. Claude's PRs are PRs.
• Pin the action. The docs use @v1. For a job that holds write permissions, pinning a full commit SHA is the standard GitHub hardening advice, and the cost is updating it on purpose.

If you want a hard stop on specific commands inside the job, Claude Code hooks work in CI the same way they work on your machine.

What a Run Costs and How to Cap It

Each run spends two different things:

• GitHub Actions minutes. The job runs on GitHub-hosted runners and uses your Actions minutes.
• Tokens. Based on prompt and response length, task complexity and codebase size. With an API key you pay API rates. With an OAuth token, runs use your Claude subscription.

The docs list the levers. I would turn most of them on from day one:

• --max-turns in claude_args caps iterations. claude_args: "--max-turns 5 --model claude-sonnet-5" is the docs' own example.
• Workflow timeout-minutes stops a runaway job. Pick a number you would be annoyed to exceed, say 15.
• Concurrency controls limit parallel runs so five comments in a row do not start five jobs. A group keyed on the issue or PR number works:

concurrency:
  group: claude-${{ github.event.issue.number || github.event.pull_request.number }}
  cancel-in-progress: false

• A concise CLAUDE.md, since it is read on every run.
• Specific requests and issue templates so Claude needs fewer turns to find the problem.
• A cheaper model for routine jobs. Review and triage rarely need the largest model. Set it with --model in claude_args, or leave it off to use the Claude Code default.

For org-wide tracking, the docs point to the analytics dashboard and the monitoring page. If you are on a subscription token and your allowance keeps vanishing, the reason is probably in what drains Claude Code usage fastest: long contexts, subagents and large models, all of which a busy CI job can hit.

Roll It Out Across an Organization

Quick setup and manual setup both work one repo at a time. For many repos:

1. Install the Claude GitHub App once at the organization level, on all repos or a selected list.
2. Store the secret as an organization-level Actions secret. Use an API key, not an OAuth token, for the reason covered earlier.
3. Add the workflow to each repo that should run it, or define the job once as a reusable workflow that each repo calls. The reusable route means one place to fix the version pin or the --max-turns value.

Bedrock, Vertex and Foundry

By default the action calls the Claude API directly. To route inference through your own cloud account instead, set one input:

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

All three authenticate through OIDC identity federation, so no static cloud credentials sit in the repository. The setup has its own page in the docs, including a custom GitHub App with APP_ID and APP_PRIVATE_KEY secrets, and I would follow that page step by step instead of improvising.

Troubleshooting

Claude does not respond to @claude.

• Check the GitHub App is installed on the repo and workflows are enabled.
• Check the secret exists in repository secrets.
• Check the comment has @claude as a whole word.
• Check the commenting user has write access.

CI does not run on Claude's commits. GitHub does not trigger workflows on commits made with the default GITHUB_TOKEN. If you pass github_token: ${{ secrets.GITHUB_TOKEN }} to the action, remove it so the action authenticates as the Claude GitHub App, or pass a custom app token. Also check that your CI triggers include the events Claude's pushes produce, such as push or pull_request. This one bites almost everyone: Claude opens a PR, the checks never start, and the PR looks stuck.

Authentication errors. Test the key or token locally with claude before debugging the workflow. A dead credential looks the same as a workflow bug from the outside.

A review job passes but nothing shows on the PR. You are in automation mode without --comment and the inline comment tool. See the review section above.

Still on @beta. Update to v1: change @beta to @v1, remove the mode input, replace direct_prompt with prompt, and move CLI options such as max_turns and model into claude_args. custom_instructions becomes --append-system-prompt.

Where This Fits in Your Workflow

My view is that the action earns its keep in two places and wastes money in a third.

It earns its keep on small, well-specified tickets, where the fix is a paragraph of description and a test. Typos in docs, a missing null check, a dependency bump with a changelog to read. These are the jobs where a twenty-minute wait for a draft PR beats context-switching.

It also earns its keep as a second reader on pull requests, especially on a team where review is the bottleneck. Used that way it is a filter that catches the obvious mistakes before a human spends attention. If review volume is your actual problem, the AI code review bottleneck is worth a read before you add more generated code to the pile.

It wastes money when the task is vague. "Improve the performance of the app" will burn turns, produce a sprawling diff and teach your team to distrust the bot. The fix is the same as in any Claude Code session: smaller tasks, clearer instructions. If you are new to the tool itself, start with how to use Claude Code locally before you hand it your CI.

A sensible rollout looks like this:

1. Run /install-github-app on one low-risk repo.
2. Start with the review workflow, read-only permissions, --max-turns set.
3. Add the @claude workflow once you trust the reviews.
4. Write the project rules into a short CLAUDE.md.
5. Add concurrency and a timeout.
6. Move to an org-level API key and a reusable workflow when a second repo wants it.

Frequently Asked Questions

What is Claude Code GitHub Actions? It is a GitHub Action, anthropics/claude-code-action, that runs Claude Code in your workflows. Mention @claude in a PR or issue comment and it analyzes code, implements changes and pushes commits. With a prompt it can run on any GitHub event.

How do I install Claude Code on GitHub? Run /install-github-app inside Claude Code in your repository. It installs the Claude GitHub App, saves an authentication secret and opens a pull request with the workflow files. You need admin access and the GitHub CLI authenticated with gh auth login.

Is Claude Code GitHub Actions free? The action is open source, but each run uses GitHub Actions minutes and either API tokens or your Claude subscription allowance. Cost depends on prompt length, task complexity and codebase size.

Does Claude Code GitHub integration work with a Claude Pro or Max subscription? Yes. Generate a token with claude setup-token and store it as CLAUDE_CODE_OAUTH_TOKEN. Pro, Max, Team and Enterprise plans can do this. Runs then use your subscription instead of API billing.

Should I use an API key or an OAuth token? Use an API key for shared and team repos. An OAuth token is tied to the subscription of the person who generated it, so it breaks when that person leaves and spends their personal allowance.

How do I trigger Claude in a pull request? Comment @claude followed by your request, from a user with write access to the repository. The trigger phrase is configurable with trigger_phrase.

Can Claude Code review pull requests automatically? Yes, two ways. Add a workflow that runs a review skill on pull_request events, with --comment so it posts to the PR. Or, on Team and Enterprise plans, turn on the managed Code Review product, which needs no workflow file.

What is the difference between Claude Code Review and the GitHub Action? Code Review is a managed service on Anthropic infrastructure for Team and Enterprise plans. It reviews only, with read-only access. The action runs on your runners, works on any plan with a key, and can also edit code, push commits and run any prompt.

Does Claude Code GitHub work on GitLab? /install-github-app works only with github.com repositories. For GitLab pipelines, use Claude Code GitLab CI/CD.

Why is Claude not responding to my @claude comment? Check that the app is installed, workflows are enabled, the secret is set, the comment contains @claude as a full word, and the commenter has write access.

Why does CI not run on Claude's commits? GitHub does not trigger workflows for commits made with the default GITHUB_TOKEN. Remove github_token: ${{ secrets.GITHUB_TOKEN }} from the action so it authenticates as the Claude GitHub App.

Can Claude Code run on a schedule in GitHub Actions? Yes. Add a schedule trigger and a prompt. Scheduled workflows run only from the default branch, and public repos lose the schedule after 60 days without activity.

How do I limit what Claude can do in CI? Set a minimal permissions block on the job, restrict tools with --allowedTools, cap iterations with --max-turns, add a workflow timeout, and require human approval before merge.

Can I use Claude Code GitHub Actions with Bedrock or Vertex? Yes. Set use_bedrock, use_vertex or use_foundry to "true" and authenticate through OIDC federation instead of an API key.

Does the managed Code Review work with Zero Data Retention? No. It is not available to organizations with Zero Data Retention enabled or the HIPAA configuration applied.

Sources, all checked October 29, 2026: Claude Code GitHub Actions, Code Review, the claude-code-action repository with its setup guide and security notes, and the Claude GitHub App.