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 git to 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#

Diagram of the two ways the action starts: a mention in a comment, or a scheduled or event trigger
One action, two triggers: a human mentions @claude, or an event starts the run. Illustration generated by AI Frontier Post.

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, @claude by 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 (claude by 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 like claude/issue-42-<timestamp>, pushed as claude[bot].
  • Automation mode — prompt set. 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:

  1. Install the Claude GitHub App from github.com/apps/claude onto the repository. The app needs Contents, Issues, and Pull requests permissions, read and write.
  2. In the repository, go to Settings → Secrets and variables → Actions → New repository secret. Name it ANTHROPIC_API_KEY and paste your Anthropic API key as the value. Never write the key into a workflow file — secrets are the only place it belongs.
  3. Using a subscription instead of an API key? Run claude setup-token in your terminal. It prints a long-lived OAuth token without saving it; store that as a secret named CLAUDE_CODE_OAUTH_TOKEN and pass it as the claude_code_oauth_token input 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.body for comments, github.event.review.body for 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: write lets Claude push branches; pull-requests: write and issues: write let it comment; id-token: write supports the action's OIDC authentication path; actions: read lets Claude read CI results on PRs so it can discuss a failing check instead of guessing.
  • anthropics/claude-code-action@v1 is 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_args carries the CLI flags. --max-turns 20 caps the session at twenty agentic turns, and --model sonnet picks the model by alias — sonnet, opus, haiku, and fable are 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#

Diagram of a pull request flowing through a robot reviewer and coming out as an approval comment
The review workflow: a PR opens, Claude reads the diff, and findings land as inline comments. Illustration generated by AI Frontier Post.

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.
  • --allowedTools grants exactly the GitHub access the prompt needs. Bash(gh pr comment:*), Bash(gh pr diff:*), and Bash(gh pr view:*) let Claude read the diff and post comments — and nothing else. The gh CLI 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: true turns 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 10 bounds the run further. Save Sonnet for the review workflow, where judgment matters.
  • The prompt forbids inventing labels. It makes Claude run gh label list first and use only labels that already exist. Without that sentence, the model will cheerfully create needs-triage-urgent-v2 on your repo — and the action will let it, because gh issue edit is 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-turns is 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-minutes bounds 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: true on 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_prs defaults to true, so the action will run on a fork's PR — but restrict_untrusted_prs also defaults to true, which denies commands that commonly run code from the checkout (package managers, test runners, shells) on PRs from authors without write access, even if claude_args allows 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 with contents: write or 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 Bash is 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 the gh subcommands the job needs, and never grant bare Bash in a workflow triggered by outsiders.
  • Commit signing is available and off by default. use_commit_signing: true signs Claude's commits with GitHub's commit signature verification, so a forged claude[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_output input that dumps all Claude messages, including tool results, into the run log — which is publicly visible on public repos. It defaults to false. 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 the if: gate — the phrase must be in the comment body for issue_comment, the review body for pull_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, and timeout_minutes. Everything now goes through prompt and claude_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_TOKEN instead of the app's token. Install the Claude GitHub App — pushes made with its token trigger downstream workflows; pushes made with GITHUB_TOKEN deliberately 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_args must 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.