Claude Code GitHub Actions: @claude mentions, reviews and issue-to-PR

Claude Code GitHub Actions runs Claude Code inside your repository's workflows, so anyone with write access can mention @claude on an issue or pull request and get code, answers or commits back. This guide covers setup, the three workflow patterns that matter (mentions, automated review, scheduled jobs), turning issues into pull requests, permissions, secrets and cost control.

What is Claude Code GitHub Actions?

Claude Code GitHub Actions is an official GitHub Action, anthropics/claude-code-action, that runs Claude Code inside your repository's workflows. You mention @claude in an issue or pull request comment and Claude reads the code, answers, implements changes and pushes commits. You can also give it a fixed prompt so it runs automatically on any GitHub event.

Typical uses:

• Answering "how does this work?" questions on a pull request.
• Fixing a bug described in a comment and pushing the fix to the PR branch.
• Turning a well-written issue into a branch with an implementation.
• Reviewing every pull request with your team's rules.
• Running scheduled jobs such as a daily summary of commits and open issues.

The action is built on the Claude Agent SDK and runs on your GitHub runners. It's separate from Claude Code Review, a managed reviewer for Team and Enterprise plans that needs no workflow file; our AI code review guide compares the two.

How do you set up Claude Code GitHub Actions?

The quickest path is to run /install-github-app inside Claude Code in your repository. It installs the Claude GitHub App, stores a secret and opens a pull request with the workflow files. You need admin access to the repository, and the command works only with github.com remotes.

Quick setup

1. Install the GitHub CLI and run gh auth login.
2. Open claude in the repository and run /install-github-app.
3. Choose how to authenticate. Claude Code reuses an existing API key, or lets you create a long-lived token from your Claude subscription.
4. Select the workflows you want (the mention workflow, and optionally the review workflow).
5. Create and merge the pull request Claude Code opens in your browser.
6. Test it: comment @claude what does this repository do? on any issue.

Manual setup

Use this when you don't run Claude Code locally or want full control:

1. Install the Claude GitHub App on the repository.
2. Add one repository secret:
   • ANTHROPIC_API_KEY: an API key from the Claude Console, billed per token.
   • CLAUDE_CODE_OAUTH_TOKEN: created locally with claude setup-token, which uses your Pro, Max, Team or Enterprise subscription.
3. Copy examples/claude.yml into .github/workflows/.
4. If you use the OAuth token, change the anthropic_api_key line to claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

For an organization, install the app once at the organization level and store the secret as an organization Actions secret. Anthropic recommends an API key rather than an OAuth token for shared secrets, because an OAuth token is tied to the subscription of the person who created it. Workload identity federation through GitHub OIDC is also supported if you'd rather store no long-lived secret.

How do you make Claude respond to @claude mentions?

Leave out the prompt input and the action runs in interactive mode: it waits for the trigger phrase @claude in a comment, a pull request review or a newly opened issue, then replies in a comment and updates it as it works.

This is the workflow from the official docs:

name: Claude Codeon:  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 }}

What each non-obvious part does:

• id-token: write is required for the action's default GitHub App authentication.
• actions: read lets Claude read CI results on pull requests, so it can fix failing checks.
• The if condition stops runners from starting on comments that don't mention Claude.
• actions/checkout gives Claude a copy of the repository to work in.

Then comment with a specific request:

@claude the date filter on /reports ignores the user's time zone.Fix it in lib/dates.ts, add a test for a user in UTC-8, and keepthe public API of formatRange unchanged.

If Claude doesn't respond, check these in order:

1. The Claude GitHub App is installed on this repository.
2. Workflows are enabled for the repository.
3. The secret name in the workflow matches the secret you created.
4. The comment contains @claude as a whole word, not /claude or @claude-bot.
5. The person commenting has write access.
6. The API key or token works locally: run claude with it before debugging the workflow.

Specific requests finish in fewer turns, which also makes them cheaper. Our guide on how to write tasks for AI coding agents has templates.

How do you turn GitHub issues into pull requests with Claude?

Add the issues event to the workflow and write @claude in an issue's title or body. Claude creates a new branch, implements the change, pushes commits and replies with a link to a pre-filled pull request page. You open the pull request yourself, so branch protection rules still apply.

The official examples/claude.yml already includes this. The relevant parts:

on:  issues:    types: [opened, assigned]  issue_comment:    types: [created]jobs:  claude:    if: |      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

According to the action's FAQ, Claude doesn't create pull requests by default, never pushes to branches other than its own or the PR branch where it was invoked, and won't merge, rebase or force push, even if you grant the git tools. On an open pull request it pushes to the existing branch; for an issue it always creates a new branch.

An issue that an agent can finish without asking questions looks like this:

@claudeProblem: CSV export on /invoices drops rows with a comma in thecustomer name.Expected: names with commas are quoted per RFC 4180.Where: src/export/csv.ts (toCsvRow). Tests in src/export/csv.test.ts.Done when:- A test with the name "Acme, Inc." passes.- Existing export tests still pass (npm test -- csv).- No changes to other export formats.

How do you run automated pull request reviews with Claude?

Give the action a prompt and trigger it on pull_request events. With a prompt, the action runs in automation mode and doesn't wait for a mention. The documented review workflow installs the code-review plugin and posts findings as inline comments:

name: Code Reviewon:  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 details matter here. The --comment argument makes Claude post its review on the pull request; without it, findings only appear in the workflow log. The claude_args line must name the inline comment tool, because the action only starts that tool's server when --allowedTools lists it.

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

Put your review rules in CLAUDE.md at the repository root. Claude reads it on every run; see CLAUDE.md best practices for what to include.

How do you run Claude on a schedule?

Trigger the workflow with schedule and pass a prompt. With a plain-text prompt, Claude has no shell or GitHub API access until you grant tools through --allowedTools in claude_args or permission rules in the settings input.

name: Daily Reporton:  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"

GitHub runs scheduled workflows only from the default branch, and in public repositories it disables a schedule after 60 days without repository activity. Results go to the workflow run log unless the prompt tells Claude to post somewhere and it has a tool that can.

Useful scheduled jobs: dependency update summaries, stale issue triage, a weekly list of flaky tests from CI logs, or a changelog draft from merged pull requests.

How do you secure Claude Code GitHub Actions?

Grant the fewest permissions and tools each workflow needs, keep credentials in GitHub Secrets, and treat text in issues and pull requests as untrusted input. The action already enforces two checks: on issue and PR events the triggering user needs write access, and bot accounts are rejected unless listed in allowed_bots.

One more gotcha: GitHub doesn't trigger workflows on commits made with the default GITHUB_TOKEN. If you pass github_token: ${{ secrets.GITHUB_TOKEN }}, your CI won't run on Claude's commits. Leave it out so the action authenticates as the Claude GitHub App.

How do you control the cost of Claude in CI?

Each run costs GitHub Actions minutes plus Claude usage: API tokens with an API key, or subscription usage with an OAuth token. Cap the work each run can do and give Claude context up front so it needs fewer turns.

• Add --max-turns to claude_args, for example claude_args: "--max-turns 10".
• Pick the model per workflow with --model; reviews and reports may not need the largest model.
• Set timeout-minutes on jobs to stop runaway runs.
• Use a concurrency group so a burst of comments doesn't start ten parallel jobs.
• Keep CLAUDE.md short, since it's read on every run.
• Use issue templates so requests arrive with the context Claude needs.

GitHub Actions suits short, event-driven tasks. For longer work, such as a queue of tasks an agent works through overnight, a persistent machine fits better; Orkio runs Claude Code on an always-on cloud box that clones your repositories, pushes branches and opens pull requests while you're away. More on that pattern in background coding agents.

How to start with Claude Code GitHub Actions today

1. Run /install-github-app in a test repository, or follow the manual setup.
2. Merge the workflow pull request and comment @claude on an issue to confirm it works.
3. Write a short CLAUDE.md with build, test and style commands.
4. Add --max-turns, a job timeout and a concurrency group.
5. Try one issue-to-branch task with clear acceptance criteria.
6. Add the review workflow, or Claude Code Review if you're on a Team or Enterprise plan.
7. Review every change Claude pushes before you merge it.

Frequently asked questions