Claude Code GitHub Actions: @claude Mentions and PR Review

Claude Code doesn’t have to live on your laptop. With Claude Code GitHub Actions you mention @claude on an issue or pull request and Claude reads the code, makes changes and pushes commits from a GitHub runner. You can also give it a prompt and run it on any GitHub event, from PR review to a daily report.

This guide walks through setup, the workflows worth copying, and the settings that keep it safe and affordable. Everything is verified against the official GitHub Actions docs and the anthropics/claude-code-action README as of October 2026. Our claude-code-action tool profile has the quick summary.

What it is (and what it isn’t)

anthropics/claude-code-action is a GitHub Action that runs Claude Code inside your workflows. It’s built on the Claude Agent SDK and executes on your own runner; API calls go to the provider you choose.

Don’t confuse it with two related products:

• Code Review: automatic review on every pull request without writing a workflow. Our Claude Code review comparison weighs it against /code-review and this action.
• Claude Code in the cloud: full Claude Code sessions on Anthropic’s infrastructure.

The action is the one you configure with YAML in .github/workflows/.

Quick setup with /install-github-app

You need admin access to the repository, and it must be on github.com.

1. Install the GitHub CLI and run gh auth login.
2. Open claude in the repository and run /install-github-app.
3. Claude Code installs the Claude GitHub App, then sets up a secret. It reuses an API key it already has, or lets you choose between pasting an API key and creating a long-lived token from your Claude subscription.
4. It saves the secret as ANTHROPIC_API_KEY (API key) or CLAUDE_CODE_OAUTH_TOKEN (subscription token), pushes a branch with the workflow files you selected, and opens a pull request in your browser.
5. Merge that pull request. @claude now works.

If you select the review workflow, Claude posts reviews on the pull request itself: inline comments on issues it finds, or one summary comment if it finds none. To refresh an older generated workflow, run /install-github-app again and choose Update workflow file with latest version.

Manual setup

Use this path if you don’t run Claude Code locally, the command fails, or you want full control.

1. Install the Claude GitHub App. The action relies on three of its permissions: Contents, Issues and Pull requests, each read and write. The app’s full permission set is broader because other Claude features share it. If your organization only accepts the minimum, create a custom GitHub App with just those three, following the action’s setup guide.

2. Add one secret:

Secret	Source	Workflow input
ANTHROPIC_API_KEY	API key from the Claude Console	anthropic_api_key
CLAUDE_CODE_OAUTH_TOKEN	Run claude setup-token locally (Pro, Max, Team, Enterprise)	claude_code_oauth_token

3. Copy the workflow. Put examples/claude.yml into .github/workflows/. As committed, it answers @claude mentions using ANTHROPIC_API_KEY.

Interactive vs automation mode

The action picks its mode from your configuration:

• Interactive mode (no prompt input): Claude waits for the trigger phrase, @claude by default, in a comment, review, or a new issue’s title or body. Progress and results appear as a comment.
• Automation mode (prompt input set): Claude runs on the event without a mention. Results go to the workflow log unless the prompt tells Claude to post and it has a tool that can.

Two checks run before Claude starts in both modes. On issue and PR events the triggering user needs write access (use allowed_non_write_users plus your own github_token to widen that). And bot actors are rejected unless listed in allowed_bots, which prevents loops.

Workflow 1: 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 }}

Why each piece is there: id-token: write is needed for the action’s default GitHub App authentication, actions: read lets Claude read CI results, and the if keeps runners from starting on comments that don’t mention Claude.

Then ask in any issue or PR:

@claude implement this feature based on the issue description
@claude fix the TypeError in the user dashboard component

Using a subscription token? Replace the anthropic_api_key line with:

claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

Workflow 2: automated PR review

The prompt input accepts a skill invocation as well as plain text. This workflow installs Anthropic’s code-review plugin and runs it on every non-draft PR update:

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-code.git"
          plugins: "code-review@claude-code-plugins"
          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 on the PR. Without it, findings only appear in the run log.
• claude_args must name the inline-comment tool, because the action only starts that MCP server when --allowedTools lists it.

Claude skips draft and closed PRs, trivial or automated ones, and PRs it already commented on. On public repositories, GitHub withholds secrets from fork PRs, so this runs only for branches in the same repository.

To run your own skill, check out the repo first so .claude/skills/ is on the runner, then pass /your-skill as the prompt. For plugin skills, use the namespaced /plugin-name:skill-name form. Our plugins guide explains marketplaces and namespacing.

Workflow 3: scheduled jobs

With a prompt, any GitHub event works, including cron:

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

A plain-text prompt has no shell or GitHub API access until you grant tools with --allowedTools in claude_args or permissions.allow rules in the settings input. GitHub only runs schedules from the default branch and disables them in public repos after 60 days without activity.

Key inputs and claude_args

Input	Purpose
prompt	Instructions or a skill invocation; omit for interactive mode
claude_args	Any Claude Code CLI arguments
anthropic_api_key / claude_code_oauth_token	Authentication
github_token	Override the GitHub App identity
plugin_marketplaces / plugins	Install plugins before running
settings	Claude Code settings as JSON or a file path
trigger_phrase	Change @claude to something else
use_bedrock / use_vertex / use_foundry	Route inference through a cloud provider

claude_args accepts the same flags as headless mode, for example:

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

Without --model, the action uses Claude Code’s default model. If you already script Claude Code locally, everything in our headless mode guide carries over.

Cloud providers and keyless auth

To bill through your own cloud account, set use_bedrock: "true" (Amazon Bedrock), use_vertex: "true" (Google Cloud’s Agent Platform) or use_foundry: "true" (Microsoft Foundry). All three authenticate through OIDC identity federation, so no static cloud credentials sit in the repo. Quick setup doesn’t cover these; follow the cloud-provider page in the docs.

For the Claude API there’s also workload identity federation: the action exchanges the workflow’s GitHub OIDC token for API access through a Claude Console service account. Set anthropic_federation_rule_id and anthropic_organization_id (plus optional service account and workspace IDs) and grant id-token: write.

Rolling out to an organization

• Install the Claude GitHub App once at organization level.
• Store the secret as an organization Actions secret. Use a Console API key here rather than an OAuth token, which is tied to one person’s subscription.
• Add the workflow to each repo, or define it once as a reusable workflow.

Costs and guardrails

Each run consumes GitHub Actions minutes and Claude usage (API tokens, or your subscription with an OAuth token). Keep both down:

• Write specific @claude requests and use issue templates for context.
• Keep CLAUDE.md concise: Claude reads it on every run.
• Set --max-turns in claude_args, plus workflow timeout-minutes and concurrency.
• Grant the workflow only the permissions it needs, and review Claude’s changes before merging.
• Never commit keys or tokens. Always reference GitHub Secrets.

See the Claude Code pricing guide for how plan usage and API billing compare.

Troubleshooting

Symptom	Fix
No response to @claude	App installed? Workflows enabled? Secret set? @claude as a whole word? Commenter has write access?
CI doesn’t run on Claude’s commits	Remove github_token: ${{ secrets.GITHUB_TOKEN }} so the action uses the App identity, or pass a custom app token
Auth errors	Test the key or token locally with claude first
Workflow references @beta	Switch to @v1, remove mode, rename direct_prompt to prompt, move max_turns/model into claude_args

GitHub Actions in your Claude kit

The action reads the same CLAUDE.md, skills and plugins as your local sessions, so a well-built Claude kit works in CI for free. Write the review checklist once as a skill, run it locally while you code, and let the workflow apply it to every PR. For choosing what goes where, see skills vs subagents vs hooks.