Put Claude Code on autopilot: the complete GitHub Action tutorial
Claude Code’s GitHub Action hit v1.0 on November 19. Set up @claude mentions, automated PR reviews, and issue triage — every workflow validated with actionlint before you commit it.
@claude and it works your issue, or set a prompt and it reviews every PR and triages every issue on its own. This guide builds all three workflows, validated with actionlint before you commit them.- Version 1.0 went generally available on November 19, 2026 (v1.0.286 the next day); the repo has roughly 10,000 stars, is MIT-licensed, and declares 41 inputs.
- The action detects its own mode from one input: no
promptmeans interactive @claude mentions; apromptmeans automation on any event. - This guide builds three workflows: a @claude mention responder, an automated PR review, and issue triage — all three pass actionlint 1.7.10 with zero findings.
- Cost is bounded by
--max-turns, a per-workflow--model,timeout-minutes, and concurrency groups — never by hoping the run is short. - Fork PRs are fenced by default (
restrict_untrusted_prs), andallowed_non_write_users: "*"is the sharp edge: minimal permissions only, never with write access.

Claude Code spent its first year in the terminal. You typed, it edited, you reviewed. That loop works, but it only runs while you're at the keyboard — the moment a teammate opens a pull request at 11pm or a user files an issue on a Saturday, the agent is asleep.
The official GitHub Action moves Claude Code into your repository's automation. It answers @claude mentions in issues and pull requests, reviews every PR that opens, triages new issues, and fixes failing CI — all on GitHub's runners, with the same model and tools you'd use locally. Version 1.0 went generally available on November 19, 2026, and the action was already at v1.0.286 a day later, with roughly 10,000 stars on the repository and commits landing daily. This guide sets it up end to end: the mention responder, an automated PR review, and issue triage, with every workflow validated before you commit it.
1. What you'll need#
- A GitHub repository you administer. Admin rights are required to install the GitHub App and add secrets. Use a low-stakes repo for your first run — a side project, not production.
- An Anthropic API key (from the Anthropic Console) or a Claude Pro, Max, or Team subscription. The API key is the simple path; the subscription path uses a long-lived OAuth token instead, covered in step 3.
- About 30 minutes. No local installs are needed for the workflows themselves — they run on GitHub-hosted runners. You will need
gitto commit the workflow files.
Cost: you pay Anthropic's API rates for the tokens Claude uses on each run, or your subscription's usage if you authenticate with an OAuth token. GitHub Actions minutes are free for public repositories; on private repos they draw on your plan's monthly allowance. The cost controls in step 8 are what keep a busy repo from surprising you.
2. Two modes, one input#

The v1 action has no mode switch. It detects the mode itself from a single input, prompt:
- Interactive mode — no
prompt. The action waits for the trigger phrase,@claudeby default, in an issue or PR comment, a PR review, or the title or body of a newly opened issue. It can also start from a label (claudeby default) or when a specific user is assigned. Claude replies in a comment it keeps updating as it works, and commits it makes land on a branch named likeclaude/issue-42-<timestamp>, pushed asclaude[bot]. - Automation mode —
promptset. Claude runs on whatever event starts the workflow: a pull request opening, a schedule, a failed check. By default its results go to the workflow run log, not a comment — if you want findings on the PR, the prompt has to say so and the tools to post them have to be allowed. The PR review in step 6 shows exactly how.
Everything else is configuration. The action declares 41 inputs — auth, triggers, tools, permissions, outputs — but you will use about six of them. The three inputs that change what a run can do are prompt (the instruction), claude_args (CLI flags such as --model, --max-turns, and --allowedTools), and the auth input, anthropic_api_key or claude_code_oauth_token. The rest are guardrails, and step 9 explains the ones that matter.
One thing the action does not do: it never merges branches, rebases, or force-pushes. It creates and pushes commits only. Merging stays a human decision — or a separate workflow's job.
3. Install the app and store the secret#
The fastest path is the one Anthropic documents: open Claude Code in your terminal inside the repository and run /install-github-app. It walks you through installing the Claude GitHub App and creating the secret, then opens a pull request with the workflow files. You must be a repository admin, and this path is only for direct Anthropic API users — Bedrock, Vertex, and Foundry setups use their own docs.
Do it by hand when you want to understand what the installer did, or when the repo already has workflows you don't want overwritten:
- Install the Claude GitHub App from
github.com/apps/claudeonto the repository. The app needs Contents, Issues, and Pull requests permissions, read and write. - In the repository, go to Settings → Secrets and variables → Actions → New repository secret. Name it
ANTHROPIC_API_KEYand paste your Anthropic API key as the value. Never write the key into a workflow file — secrets are the only place it belongs. - Using a subscription instead of an API key? Run
claude setup-tokenin your terminal. It prints a long-lived OAuth token without saving it; store that as a secret namedCLAUDE_CODE_OAUTH_TOKENand pass it as theclaude_code_oauth_tokeninput instead of the API key. The token is tied to your subscription, so its usage bills like your normal Claude Code sessions.
Why the app matters, not just the secret: commits the action pushes with the default GITHUB_TOKEN do not trigger other workflows. That means your CI would silently skip every fix Claude pushes. The app's token does trigger them. If you set this up with the token alone and your tests never run on Claude's branches, this is the cause — install the app.
4. The @claude mention responder#
Create .github/workflows/claude.yml. This is the repository's own example workflow, plus three additions from the action's cost guidance: a 30-minute job timeout, a concurrency group so two mentions on the same issue queue instead of racing, and a turn cap.
name: Claude Code
# Workflow 1 — Interactive mode: answer @claude mentions in issues and PRs.
# With no `prompt` input, the action waits for the trigger phrase and replies
# in a comment it keeps updating. Source: anthropics/claude-code-action
# examples/claude.yml (v1.0.286), plus a job timeout, a per-issue concurrency
# group, and a turn cap from the action's cost guidance.
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
pull_request_review:
types: [submitted]
issues:
types: [opened, assigned]
jobs:
claude:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
(github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
runs-on: ubuntu-latest
timeout-minutes: 30
concurrency:
group: claude-${{ github.event.issue.number || github.event.pull_request.number }}
cancel-in-progress: false
permissions:
contents: write
pull-requests: write
issues: write
id-token: write
actions: read # lets Claude read CI results on PRs
steps:
- name: Checkout repository
uses: actions/checkout@v6
with:
fetch-depth: 1
- name: Run Claude Code
id: claude
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: |
--max-turns 20
--model sonnet
Four details deserve attention:
- The
if:is load-bearing. Without it, the job starts a runner on every comment, review, and issue, and the action itself decides there's nothing to do. The condition checks the trigger phrase in the right field for each event type —github.event.comment.bodyfor comments,github.event.review.bodyfor reviews, the issue's body or title for new issues. Copy it verbatim; a missing clause is the most common reason the action "never runs." - Permissions are the narrowest that work for this mode.
contents: writelets Claude push branches;pull-requests: writeandissues: writelet it comment;id-token: writesupports the action's OIDC authentication path;actions: readlets Claude read CI results on PRs so it can discuss a failing check instead of guessing. anthropics/claude-code-action@v1is a floating major tag. It tracks the latest v1 release (v1.0.286 at the time of writing). Pinning to a full release tag is the conservative choice for a repo where you want to review upgrades; the floating tag is the choice the official examples use.claude_argscarries the CLI flags.--max-turns 20caps the session at twenty agentic turns, and--model sonnetpicks the model by alias —sonnet,opus,haiku, andfableare all valid, or pass a full model ID. Both flags are documented in the CLI reference; the v0.x inputs they replace (max_turns,model,allowed_tools) no longer exist, so workflows copied from older tutorials will fail — see troubleshooting.
Before committing, validate the file. I checked all three workflows in this guide with actionlint 1.7.10 (zero findings) and confirmed every input name against the action's action.yml — do the same for yours:
actionlint .github/workflows/claude.yml
# expect: no output, exit code 0
5. Test it like a reviewer would#
Commit the workflow, push, and open an issue in the repo. In a comment, write something the action has to actually do — not a greeting, a task:
@claude add a CONTRIBUTING.md that explains how to run the tests
and what the commit message convention is. Read the repo first;
don't invent tooling we don't have.
What you should see, in order: the workflow run starts under Actions; Claude posts a comment on the issue and updates it as it works; a branch appears named like claude/issue-1-<timestamp>; a pull request is opened from that branch, authored by claude[bot], with the new file. Open the PR and check the content against the repo — the instruction to read the repo first is there because an agent with no constraints will happily document a test runner you don't use.
If nothing happens at all, don't edit the workflow yet. Check Actions → the workflow run list first: if no run started, the if: gate or the app installation is the problem. If a run started and failed, the log names the cause — the six usual ones are in the troubleshooting section.
6. Automated PR reviews on every pull request#

The mention responder waits to be asked. This workflow doesn't: it runs on every pull request and reviews the diff. Create .github/workflows/claude-pr-review.yml. It is adapted from the action's own PR review example — same prompt shape, same tool allowlist, same progress-tracking flag.
name: Claude PR Review
# Workflow 2 — Automation mode: review every pull request automatically.
# With `prompt` set, the action runs on the event itself instead of waiting
# for a mention, and posts its findings on the PR. Adapted from
# anthropics/claude-code-action examples/pr-review-comprehensive.yml (v1.0.286):
# same prompt shape, same gh-based tool allowlist, same track_progress flag.
on:
pull_request:
types: [opened, synchronize, ready_for_review, reopened]
jobs:
review:
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
pull-requests: write
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v6
with:
fetch-depth: 1
- name: Review PR with Claude
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
# Progress tracking: one comment with checkboxes, updated as
# the review proceeds, marked complete when it finishes.
track_progress: true
prompt: |
REPO: ${{ github.repository }}
PR NUMBER: ${{ github.event.pull_request.number }}
Review this pull request. Focus on, in order:
1. Correctness — logic errors, wrong assumptions, broken edge cases.
2. Security — injection, auth gaps, secrets, unsafe deserialization.
3. Tests — missing coverage for the changed behavior.
4. Performance — obvious hot paths, N+1 queries, unbounded loops.
Post one inline comment per real finding, with the file and line.
Skip style nits and praise. If you find nothing above nit level,
post a single top-level comment saying the PR looks good and why.
claude_args: |
--max-turns 15
--model sonnet
--allowedTools "Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"
Three things make this workflow work where a naive "review this PR" prompt fails:
- The prompt tells Claude where the output goes. Automation mode defaults to the run log, so the prompt explicitly says to post one inline comment per real finding and a single top-level comment when there's nothing to say. Without that sentence, the review exists only in a log nobody reads.
--allowedToolsgrants exactly the GitHub access the prompt needs.Bash(gh pr comment:*),Bash(gh pr diff:*), andBash(gh pr view:*)let Claude read the diff and post comments — and nothing else. TheghCLI ships preinstalled on GitHub-hosted runners. Notice the permissions above are narrower than the mention workflow's:contents: read, because a reviewer should not be pushing commits.track_progress: trueturns the run into something you can watch. Claude posts a tracking comment with progress checkboxes and updates it as the review proceeds, instead of going silent for ten minutes and then dumping a wall of comments.
The prompt's ordering is deliberate: correctness first, security second, tests third, performance fourth — and "skip style nits and praise" last. A review bot that comments on formatting is a bot your team mutes within a week. If your repo has a review checklist, add it to the prompt; the action accepts a long one. The official examples also include variants that review only changed paths or only PRs from first-time contributors — worth copying once the basic version is running.
7. Issue triage that runs for anyone#
Issues come from strangers. By default the action ignores anyone without write access — a sensible default, and a problem for triage, which exists precisely for issues from people outside the team. This workflow opts into that, with the smallest permissions that work. Create .github/workflows/claude-triage.yml:
name: Claude Issue Triage
# Workflow 3 — Automation mode: label and acknowledge every new issue.
# Runs on issues opened by anyone, including people without write access,
# so it needs the action's allowed_non_write_users input plus an explicit
# github_token. Keep this workflow's permissions minimal: it only reads the
# repo and writes issue labels/comments. See the article's security section
# before copying the `allowed_non_write_users: "*"` line into a real repo.
on:
issues:
types: [opened]
jobs:
triage:
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
issues: write
steps:
- name: Checkout repository
uses: actions/checkout@v6
with:
fetch-depth: 1
- name: Triage issue with Claude
uses: anthropics/claude-code-action@v1
with:
prompt: |
REPO: ${{ github.repository }}
ISSUE NUMBER: ${{ github.event.issue.number }}
Triage this issue. First run `gh label list` and use ONLY labels
that already exist in this repo — never invent a label. Then:
1. Add the 1-3 labels that best describe the issue (area, kind,
and severity if those label families exist).
2. Post one short comment: what the issue is asking for in one
sentence, plus the single most useful next step for a
maintainer (a question to ask, a file to look at, or a
duplicate to check). Do not close the issue.
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
github_token: ${{ secrets.GITHUB_TOKEN }}
allowed_non_write_users: "*"
claude_args: |
--max-turns 10
--model haiku
--allowedTools "Bash(gh label list),Bash(gh issue edit:*),Bash(gh issue comment:*)"
Two decisions in this file are worth copying deliberately, not accidentally:
--model haiku. Triage is a classification task: read the issue, pick labels, write one sentence. The smallest model does it well at a fraction of the cost, and--max-turns 10bounds the run further. Save Sonnet for the review workflow, where judgment matters.- The prompt forbids inventing labels. It makes Claude run
gh label listfirst and use only labels that already exist. Without that sentence, the model will cheerfully createneeds-triage-urgent-v2on your repo — and the action will let it, becausegh issue editis in the allowlist.
Read the security note on allowed_non_write_users: "*" in section 9 before you copy this workflow into a real repository. It is the one input in this guide that trades safety for convenience, and the action's own documentation says so.
8. Keep the bill small: turns, models, timeouts#
An unattended agent with an API key and no limits is a billing incident waiting for a busy week. Four controls, all visible in the workflows above, bound the cost:
--max-turnsis the spend cap that matters most. A mention responder at 20 turns and a review at 15 turns will finish real tasks and stop real runaways. Raise it only for a specific workflow that demonstrably needs more, never globally.- Pick the model per workflow, not per repo. Haiku for triage and labeling, Sonnet for reviews and implementation, Opus only when a task has genuinely stumped the cheaper models. The alias form (
--model sonnet) is stable across releases; full model IDs change, and a pinned ID from an old tutorial will eventually stop resolving. timeout-minutesbounds the runner, not just the model. Thirty minutes for interactive and review work, ten for triage. A run that hits the timeout is a run you can investigate; a run with no timeout is a run that burns tokens until GitHub's six-hour job limit kills it.- Concurrency groups stop duplicate work. Two mentions on the same issue queue behind one group instead of running twice. For the review workflow, consider
cancel-in-progress: trueon the PR's group so a new push cancels the stale review of the old diff — but only if your team is comfortable with a review disappearing mid-write.
What you can't bound from inside the workflow is the API key itself: set a spend limit on the Anthropic API key in the Console, and check the first week's usage before you enable the action on a high-traffic repo.
9. Security checklist: least privilege, forks, and prompt injection#
Putting an agent with an API key on a public issue tracker is a security decision, not just a productivity one. The action ships with sane defaults — verify them rather than trusting them:
- Fork pull requests are fenced by default.
allow_fork_prsdefaults totrue, so the action will run on a fork's PR — butrestrict_untrusted_prsalso defaults totrue, which denies commands that commonly run code from the checkout (package managers, test runners, shells) on PRs from authors without write access, even ifclaude_argsallows them. Leave both defaults alone unless you have a specific reason and have read the action's security doc. allowed_non_write_users: "*"is the sharp edge. It lets anyone trigger a run that holds your API key. The action's own description warns that it best-effort scrubs secrets from subprocess environments when this is set, and that this reduces but does not eliminate prompt injection risk — only use it for workflows with very limited permissions and validate all outputs. The triage workflow qualifies: it can only read the repo and write labels and comments. Never pair that input withcontents: writeor a broad--allowedTools.- Never let untrusted content reach a shell. An issue body is attacker-controlled text. A prompt that tells Claude to "follow the instructions in the issue" plus a tool allowlist that includes
Bashis a prompt-injection hole: the issue can instruct the agent to exfiltrate the secret from the environment. Keep the tool allowlist in automation workflows to theghsubcommands the job needs, and never grant bareBashin a workflow triggered by outsiders. - Commit signing is available and off by default.
use_commit_signing: truesigns Claude's commits with GitHub's commit signature verification, so a forgedclaude[bot]commit is detectable. Turn it on for any repo where commit provenance matters. - Keep the key out of logs. The action has a
show_full_outputinput that dumps all Claude messages, including tool results, into the run log — which is publicly visible on public repos. It defaults tofalse. Leave it there except when debugging a private repo.
10. Troubleshooting: the six failures you'll actually hit#
- Nothing happens when you comment
@claude. Check three things in order: the app is installed on this repository (not just the org), Actions is enabled for the repo, and the comment matches theif:gate — the phrase must be in the comment body forissue_comment, the review body forpull_request_review, or the issue title or body for new issues. A mention in a PR description won't trigger it. - The run fails on an input name from an old tutorial. v1 removed the v0.x inputs:
mode,direct_prompt,override_prompt,custom_instructions,model,allowed_tools,disallowed_tools,anthropic_model,trigger_phrase, andtimeout_minutes. Everything now goes throughpromptandclaude_args. The action's migration guide maps each one. - Claude pushes a fix and your CI never runs on it. The workflow used the default
GITHUB_TOKENinstead of the app's token. Install the Claude GitHub App — pushes made with its token trigger downstream workflows; pushes made withGITHUB_TOKENdeliberately do not. - The review exists only in the run log. That's automation mode's default. The prompt must instruct Claude to post its findings, and
claude_argsmust allow the tools that post them —Bash(gh pr comment:*)in workflow 2. A prompt that says "review this PR" without a posting instruction produces a review nobody sees. - The run ends mid-task with no error. You hit
--max-turns. The action stops the session when the cap is reached, successfully or not. Raise the cap for that workflow, or split the prompt into a smaller task — a review that needs 40 turns is usually a review whose scope is too broad. - The triage workflow labels things wrong on day one. It can only choose from labels that exist, and a repo with three labels gets three-label triage. Seed the label set first —
bug,feature,docs,question, plus area labels for your codebase — then let the workflow use them.
Which approach should you use?#
- The mention responder — start here. It's the lowest-risk automation: a human asks, Claude acts, a human reviews the PR. Use it for implementation tasks, questions about the codebase, and small fixes. Every repo with Claude Code users should have it.
- Automated PR review — add it once the responder works. It's the highest-value automation for a team that reviews a lot of code, and the easiest to tune: the prompt is the review checklist, and every complaint from the team is a prompt edit. Keep the tool allowlist narrow and the model on Sonnet.
- Issue triage — add it when new issues arrive faster than maintainers read them. It pays off on public repos with real inbound volume. Skip it on a quiet repo; the triage comment on your one issue a month will look like a bot talking to itself.
- None of them — if the repo's value is in human judgment (a design doc repo, a legal repo), or if nobody will read the reviews, an agent that comments on everything is noise. The action is a force multiplier for maintainers, not a replacement for them.
The pattern that wins in practice is layered: the responder handles the work people ask for, the review workflow handles the work nobody asked for but everyone needs, and triage keeps the front door tidy. Each workflow has its own permissions, its own model, and its own turn cap — tune them independently, and disable any one of them by deleting its file.
The takeaway#
Start with the mention responder this week. It takes one secret, one workflow file, and one test comment to prove the loop works — and from that point, every other automation in this guide is a variation on the same three inputs: prompt, claude_args, and the auth token. Add the PR review next, then triage, each with its own permissions and its own model. Validate every workflow with actionlint before you commit it, keep the tool allowlists as narrow as the job allows, and remember the hierarchy: the action automates, the permission system secures, and you still merge.
An agent that works while you sleep is worth having. An agent that works while you sleep, with a turn cap, a narrow allowlist, and a human holding the merge button, is worth trusting.
Sources: the claude-code-action repository (action.yml inputs and defaults, example workflows, README, usage and security docs; v1.0.286, November 20, 2026), the Claude Code CLI reference (--max-turns, --model, --allowedTools, claude setup-token), and the release history (v1.0 GA November 19, 2026). All three workflows in this guide were validated with actionlint 1.7.10 and PyYAML, and every input name was checked against the action's source. The live GitHub run is the reader's verification step — step 5 tells you exactly what to look for.