Claude Code GitHub Actions: Setup and @claude Guide

Claude Code GitHub Actions lets you type @claude in a pull request or issue and have Claude Code read the code, answer, and push changes from inside your repository's own workflow. Setup is three pieces: the Claude GitHub App, one authentication secret, and one workflow file. You can do all three with a single command, or by hand.

This guide follows Anthropic's GitHub Actions documentation and the claude-code-action repository as of October 2026. It covers both setup paths, what actually triggers a run, how authentication works, the permissions the workflow needs, and the security rules that matter before you point it at a public repository.

Claude Code GitHub Actions setup: quick or manual

Anthropic documents two routes. Both need admin access to the repository.

Quick setup

Open claude in the repository, run /install-github-app, and follow the prompts. Claude Code installs the app, then handles the secret. If it already has an API key it reuses that. Otherwise you choose between creating a long-lived token from your Claude subscription or pasting in an API key. It saves the credential as a repository secret named ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN.

Then it pushes a branch with the workflow files you picked and opens GitHub with a pull request ready to create. Merge that pull request and @claude works in the repo. If the repository's remote is on gitlab.com or bitbucket.org, the command prints a notice and stops instead.

Manual setup

1. Install the Claude GitHub App on the repository. The Action relies on three of its permissions: Contents, Issues, and Pull requests, each read and write.
2. Add an authentication secret to the repository. See GitHub's guide to using secrets in GitHub Actions.
3. Copy examples/claude.yml into .github/workflows/. The docs call it a working workflow rather than a sketch. As committed, it authenticates with ANTHROPIC_API_KEY.

Test it by commenting @claude on an issue or pull request.

The smallest workflow that works

This is the "respond to @claude mentions" example from Anthropic's docs. It runs in comment-driven mode:

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 aren't boilerplate:

• id-token: write is required for the Action's default GitHub App authentication.
• actions: read lets Claude read CI results on pull requests.
• actions/checkout gives Claude a local copy of the repository to work in.
• The if line stops runners from starting on comments that never mention @claude.

The claude.yml in the repo goes further: it also listens for newly opened or assigned issues and submitted pull request reviews. If you want those events, copy that file instead of this shorter one.

What triggers Claude

The Action picks its mode from your workflow. No prompt input means interactive mode. A prompt input means automation mode.

You can change the phrase with trigger_phrase. The docs note that the comment has to contain @claude as a whole word, so /claude or @claude-bot won't match unless you've reconfigured it.

Two of the documented automation patterns are worth knowing by name:

• Review on every pull request. Anthropic's example installs the code-review plugin and runs its skill when a PR is opened, updated, reopened, or marked ready for review. It skips drafts and closed PRs. For this exact job, the docs also point to a separate Code Review feature that needs no workflow file.
• A scheduled report. A schedule trigger with a plain-text prompt works, but Claude gets no shell or GitHub API access until you grant the tools that prompt needs. GitHub only runs scheduled workflows from the default branch, and in public repositories it disables a schedule after 60 days without repository activity.

The repo's solutions guide lists more patterns, including path-specific reviews and issue triage.

Authentication options

For a secret shared across an organization, the docs recommend an API key rather than an OAuth token, because the token belongs to one person's subscription. To roll out across many repositories, install the app once at the organization level, store the secret as an organization-level Actions secret, and either add the workflow file per repository or define it once as a reusable workflow.

Permissions: what the workflow needs and what the app gets

There are two permission layers, and they get confused.

The workflow's permissions: block is GitHub's, and you control it. The examples above grant write access to contents, pull requests, and issues for the interactive workflow. Anthropic's review example gets away with read-only on all three, because Claude only comments. The rule from the docs: grant the workflow only what it needs.

The GitHub App's permissions are set when you install it. The docs are blunt that the app is shared by several Claude features, so installing it grants a wider set than this Action uses, and GitHub doesn't let you accept a subset. If your organization wants only Contents, Issues, and Pull requests, the documented route is to create a custom GitHub App. A custom app covers only this Action; Code Review and web auto-fix still need the official one.

Separately, what Claude may do inside a run follows Claude Code's own permission rules. By default Claude can't run Bash commands unless you allow them. You open that up with --allowedTools in claude_args, or a permissions.allow rule in the settings input. If those rules are new to you, our Claude Code permissions guide explains how they work on your own machine; the workflow uses the same ideas.

Passing CLI options and using CLAUDE.md

Anything you'd pass to the Claude Code CLI goes in the claude_args input:

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

The documented common arguments are --max-turns to cap conversation turns, --model to pick a model (without it the Action uses Claude Code's default), --mcp-config for MCP servers, --allowedTools for permitted tools, and --debug. Running Claude Code non-interactively is a CLI topic in its own right; our headless mode guide covers it. The Action is also built on the Claude Agent SDK, which is the route for automation that lives outside GitHub Actions.

Project rules go in CLAUDE.md in the repository root. Claude follows it when creating pull requests and answering requests, so put code style, review criteria, and preferred patterns there. Keep it short: the docs point out that Claude reads it on every run, which also matters for cost.

One security detail that affects it: on pull requests, the Action restores CLAUDE.md, .claude/, .mcp.json, and a few other Claude config paths from the base branch before Claude starts. A pull request that edits CLAUDE.md does not change the instructions Claude reads during that run.

Billing and cost control

Anthropic describes the model, not a rate. Each run uses GitHub Actions minutes on GitHub-hosted runners, and model usage: API tokens if you authenticate with a key, or your Claude subscription if you use an OAuth token. Token use grows with prompt length, task complexity, and codebase size.

The docs list the levers: specific @claude requests that need fewer turns, issue templates that supply context up front, a concise CLAUDE.md, --max-turns in claude_args, workflow-level timeouts, and GitHub's concurrency controls to limit parallel runs. For current rates, use GitHub's and Anthropic's own pricing pages.

Security rules before you turn it on

Read the security documentation once. The parts people skip:

• Write access is required to trigger it. On issue, pull request, comment, and review events, the person triggering Claude must have write access. allowed_non_write_users bypasses that and the docs call it risky; it is meant only for workflows with very limited permissions.
• Bots are blocked by default. Use allowed_bots for specific bots. The docs warn that on a public repository, '*' can let outside GitHub Apps invoke the Action with a prompt they control. Prefer an explicit list.
• Prompt injection is real. Contributors can hide instructions in HTML comments or invisible characters. The Action strips several of those, but the docs recommend reviewing the raw content of anything from external contributors before tagging Claude on it.
• Don't check out untrusted code on pull_request_target. Those events run with the base repository's secrets. The docs say to keep the base ref at the workspace root and put the PR head in a subdirectory.
• Never hardcode a key. Store it as a GitHub secret. Leave show_full_output off, since its logs are publicly visible in public repositories.
• Claude doesn't open the pull request for you by default. It commits to a branch and links to a prefilled PR creation page, so a human still clicks the button. It also can't approve a pull request.

Review what Claude pushes before you merge it, exactly as you would a teammate's branch.

When Claude doesn't respond

The docs' troubleshooting checklist:

1. The GitHub App isn't installed on that repository.
2. Workflows are disabled for the repository.
3. The secret is missing or named differently from what the workflow reads.
4. The comment doesn't contain @claude as a complete word.
5. The commenter doesn't have write access.

If Claude's commits don't trigger your CI, the cause is usually GitHub itself: it doesn't start workflows for commits made with the default GITHUB_TOKEN. The fix in the docs is to stop passing github_token, so the Action authenticates as the Claude GitHub App, or to pass a custom app token.

Where Taku fits

Claude Code GitHub Actions is for people who maintain a repository and want an assistant inside their pull request flow. If that's you, use it; Taku is not CI and doesn't replace it.

If you're the reader who keeps seeing setups like this shared and can't reproduce them, that is the gap Taku is built for. Taku is an AI-native desktop workspace where you mirror an AI setup, app, skill, or workflow that someone already got working, run it, remix it, and keep it. The free apps library shows what that looks like in practice. Taku is in Beta, and the Mac app is available now.

FAQ

How do I set up Claude Code GitHub Actions?

Run /install-github-app in Claude Code from your repository, then merge the pull request it opens. Or do it by hand: install the Claude GitHub App, add ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a repository secret, and copy examples/claude.yml into .github/workflows/.

What does @claude do in a pull request?

It triggers the workflow, and Claude answers in a comment on the same issue or PR, updating it as it works. Per the repo's capabilities page, it pushes to the existing branch on an open pull request and works on a new branch when triggered from an issue.

Do I need an API key, or does a Claude subscription work?

Either. Use anthropic_api_key for an API key, or claude_code_oauth_token, generated with claude setup-token, to run on your subscription. Cloud providers and workload identity federation are the other documented options.

Can Claude Code review every pull request automatically?

Yes. Anthropic's example workflow runs a code-review skill on pull_request events and posts inline comments. Anthropic also documents a separate Code Review feature that does this without a workflow file.

Does Claude Code GitHub Actions read my CLAUDE.md?

Yes. Claude follows it when creating pull requests and responding to requests. On pull requests it is taken from the base branch, not the PR's own version.

Why doesn't CI run on Claude's commits?

GitHub doesn't trigger workflows on commits made with the default GITHUB_TOKEN. Remove github_token from the Action's inputs so it authenticates as the Claude GitHub App, or pass a custom app token.

The short version

Install the app, store one secret, commit one workflow, and mention @claude. Keep the workflow's permissions small, keep bots off the allow-list, treat outside contributors' text as untrusted, and put your standards in CLAUDE.md. Anthropic's GitHub Actions page is the reference to check when inputs change.