Claude Code GitHub Actions Setup Guide (@claude + Cron)

Claude Code GitHub Actions is the official anthropics/claude-code-action@v1 integration: tag @claude in a pull request or issue and Claude reviews code, answers questions, or implements changes; point it at a cron schedule with an explicit prompt and it runs unattended. It runs on your own GitHub runner and calls the Anthropic API with your credentials. As of June 16, 2026, that API usage still draws from your normal Claude subscription limits — the planned June 15 split into a separate credit pool was paused.

This post covers setup (two paths), real .github/workflows YAML for an @claude-mention job and a scheduled review, the secrets table, the billing situation, and the security gotchas that bite people on public and fork PRs.

Table of Contents

1. What Claude Code GitHub Actions Does
2. Setup: Two Paths
3. The @claude-Mention Workflow
4. The Scheduled Review Workflow
5. Which Secret Goes Where
6. What It Costs After June 15
7. Security: Permissions and Prompt Injection
8. Comparing the Approaches
9. Frequently Asked Questions

What Claude Code GitHub Actions Does

anthropics/claude-code-action@v1 is a general-purpose Claude Code action for GitHub PRs and issues. It went GA on August 26, 2025, replacing the older @beta tag. Per the action's README, it "can answer questions and implement code changes," and it auto-detects which mode to run in.

There are two modes, and the action picks one for you:

• Interactive mode — triggered by an @claude mention in a comment or an issue assignment. No prompt needed. Claude reads the thread, does the work, commits to a new branch, and replies.
• Automation mode — triggered when you supply an explicit prompt (or run on schedule / pull_request). Claude executes that prompt without waiting for a mention.

The thing to internalize early: this action runs on your GitHub runner, and the Anthropic API calls go to your provider account. That means two separate cost lines — GitHub Actions runner minutes (billed by GitHub) and Claude API tokens (billed via your chosen provider). More on that below.

One safety property worth knowing up front: Claude does not open pull requests by itself. It commits to a new branch and returns a link to the GitHub PR-creation page. You click it. That human-in-the-loop step is by design, per the action's security docs.

Setup: Two Paths

Path 1: The install command (fastest)

Inside a Claude Code session, as a repo admin, run:

/install-github-app

This installs the Claude GitHub App, wires up your secret, and drops an example workflow into .github/workflows/. Admin access is required because installing a GitHub App and writing repo secrets are both privileged operations.

Path 2: Manual (when you want to see every step)

1. Install the GitHub App at github.com/apps/claude and grant it your repo.
2. Add ANTHROPIC_API_KEY to your repo secrets (Settings → Secrets and variables → Actions). The key starts with sk-ant-.
3. Copy an example workflow from the action repo into .github/workflows/.
4. Test by tagging @claude in an issue or PR comment.

Either path lands you in the same place. The official setup docs cover three authentication options:

• ANTHROPIC_API_KEY — a standalone API key, billed per token directly.
• CLAUDE_CODE_OAUTH_TOKEN — for Pro/Max subscribers. Generate it locally with claude setup-token, then store it as a repo secret.
• Workload Identity Federation — for orgs that don't want long-lived secrets at all.

If you run Claude through Amazon Bedrock or Google Vertex, you set use_bedrock/use_vertex plus the cloud provider's OIDC, and you use a GitHub App token instead of the Anthropic key.

The @claude-Mention Workflow

This is the bread-and-butter setup: someone types @claude in a PR comment, and Claude responds. Here is a minimal, current @v1 workflow.

name: Claude
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Notice there is no prompt. On comment events, when you omit the prompt, the action responds to the @claude trigger phrase automatically — that is what keeps it in interactive mode. Per the GitHub Actions docs, the action only fires when the comment actually contains @claude, so it won't burn tokens on every comment.

The permissions block is the least-privilege set: contents: write so Claude can push a branch, pull-requests: write and issues: write so it can comment. Add id-token: write only if you authenticate through OIDC for a cloud provider.

If you're upgrading an old @beta workflow, note that @v1 is a breaking change. Per the docs you must: change @beta to @v1, delete the mode: field (now auto-detected), rename direct_prompt to prompt, and move max_turns / model / custom_instructions / allowed_tools into claude_args (for example --max-turns 10, --model claude-sonnet-4-6). Old tutorials still show @beta YAML — it will fail.

The Scheduled Review Workflow

The second pattern runs Claude on a timer with an explicit prompt. Supplying a prompt is exactly what flips the action into automation mode.

name: Daily Commit Summary
on:
  schedule:
    - cron: '0 9 * * *'

jobs:
  summary:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - uses: actions/checkout@v4
      - 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 opus'

For an actual per-PR code review (rather than a daily digest), the docs recommend the code-review plugin:

name: PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - 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 ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'

Run actions/checkout before the action when you invoke a repo-local skill, or the plugin has nothing to read.

One gotcha that quietly breaks CI loops: commits pushed by the default GITHUB_TOKEN (the Actions user) do not trigger downstream CI workflows. If you want Claude's commits to kick off your test suite, use the Claude GitHub App or a custom GitHub App token via actions/create-github-app-token@v2. Otherwise Claude opens a branch, your CI stays silent, and you wonder why the checks never ran.

Which Secret Goes Where

You'll see several secret names in the docs. Here's what each one is for and when you actually need it.

Two rules that matter more than they look:

• Always reference secrets as ${{ secrets.ANTHROPIC_API_KEY }}. Never hardcode an sk-ant- key in YAML. The repo is the wrong place for it and git log is forever.
• The auto-issued GITHUB_TOKEN is short-lived and scoped to the triggering repo only — no cross-repo access, per the security docs. That's a feature; don't replace it with a broader PAT unless you have a specific reason.

What It Costs After June 15

Here's the part that's been confusing everyone, so read it carefully.

Anthropic announced a billing change for June 15, 2026 that would have moved all programmatic usage — the Agent SDK, claude -p, and Claude Code GitHub Actions — into a separate monthly "Agent SDK credit" pool billed at full API rates. That change was paused on the day it was due to take effect.

As of June 16, 2026, the support article 15036540 now opens with "We're pausing the changes to Claude Agent SDK usage described below" and states that "nothing has changed: Claude Agent SDK, claude -p, and third-party app usage still draw from your subscription's usage limits." The New Stack confirmed Anthropic "hit pause on a billing change... pulling back on the very day it was scheduled to go live (June 15)."

So, the current reality:

If you read a blog post (or a search result dated before June 15) telling you your GitHub Actions usage moved to a separate credit pool — it didn't. That information is stale. Verify against the support article, which now leads with the pause notice.

For the full backstory on the planned change and the migration checklist that was relevant before the pause, see the Claude billing change writeup. For the post-pause picture and what it means for token spend, see Claude Code costs after June 15. This post won't re-explain the billing mechanics — those two cover it.

What you do still pay either way: GitHub Actions runner minutes. The action runs on your runner, and that's billed by GitHub independent of anything Anthropic does. Two cost lines, always.

If you prefer to sidestep the subscription question entirely, authenticate with a standalone ANTHROPIC_API_KEY and pay per token: Claude Opus 4.8 is $5 per million input tokens and $25 per million output; Claude Sonnet 4.6 is $3 input and $15 output. A typical PR review reads roughly 50K input tokens (diff, surrounding context, your CLAUDE.md) and writes ~4K output. On Sonnet 4.6 that's about $0.15 input plus $0.06 output, roughly $0.21 per review. Four reviews a day for thirty days lands near $25/month in tokens — useful math whether you're drawing from a subscription or paying per token.

Cost controls that work: set --max-turns in claude_args (the default is 10 conversation turns), add a workflow-level timeout-minutes to stop runaway jobs, use GitHub concurrency to cap parallel runs, and scope @claude commands narrowly rather than firing a broad "fix everything" prompt.

jobs:
  claude:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    concurrency:
      group: claude-${{ github.ref }}
      cancel-in-progress: true
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: '--max-turns 8'

Security: Permissions and Prompt Injection

This section is where most real damage happens. Three things to get right.

Who can trigger the action

By default, only users with write access to the repo can trigger the action. GitHub Apps and bots are blocked by default. There's an allowed_non_write_users setting (and allowed_bots) you can set to '*', but doing that on a public repo is high-risk — any external party or App can then invoke the action with a prompt it controls. Leave the default unless you have a hard requirement and you've thought through the blast radius.

The fork-PR secret-leak gotcha

This is the single biggest risk, so be precise about it. Workflows triggered by pull_request_target or workflow_run run with the base repo's secrets — including your ANTHROPIC_API_KEY. If you then check out the untrusted PR head SHA to the workspace root before the action runs, you've handed attacker-controlled code an environment that holds your secrets.

The security docs give two correct patterns:

1. Check out the base branch with no ref: — so the workspace contains your trusted code, not the PR's.
2. Check the PR head into a subdirectory and pass claude_args: '--add-dir pr-head', so Claude can read the PR code without it sitting at the workspace root with your secrets.

# Reviewing a fork PR — check PR code into a subdirectory, not the root
- uses: actions/checkout@v4
  with:
    repository: ${{ github.event.pull_request.head.repo.full_name }}
    ref: ${{ github.event.pull_request.head.sha }}
    path: pr-head
- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: '--add-dir pr-head'

Prompt injection from external contributors

When Claude reads a PR or issue authored by someone outside your team, that text is untrusted input. An attacker can hide instructions in it. The action defends against this by default: it strips HTML comments, invisible characters, markdown image alt text, hidden HTML attributes, and HTML entities before Claude sees the content. That blunts the common injection vectors, though it is not a license to run the action on '*' triggers and walk away.

Don't leak your own logs

show_full_output is disabled by default for a reason — turning it on would dump tool outputs, environment, and file contents into Action logs, which are publicly visible on public repos. It auto-enables if ACTIONS_STEP_DEBUG is true, so don't flip on step debugging on a public repo while the action runs. Subprocess env secret scrubbing (CLAUDE_CODE_SUBPROCESS_ENV_SCRUB) is on by default and worth leaving on.

For a deeper treatment of injection vectors against coding agents specifically, see prompt injection in coding agents.

Comparing the Approaches

anthropics/claude-code-action is not the only way to get Claude reviewing PRs. Here's how the options line up, with honest tradeoffs.

The one people conflate with the action is Anthropic's managed Code Review — a different product. It's a research preview, Team and Enterprise only, runs on Anthropic's infrastructure (not your runner), and auto-reviews PRs without a trigger via multi-agent analysis, posting inline severity-tagged comments. Per the Code Review docs, each review averages ~$15–25 billed through usage credits and does not count against your plan's included usage, and the check run always completes neutral so it never blocks a merge. You can shape it with a REVIEW.md file (review-only instructions injected at highest priority) and your CLAUDE.md (general standards, flagged as nits). It's also unavailable under Zero Data Retention.

Don't conflate the two: the self-hosted action runs on your runner and bills through your normal Claude usage (or API key); managed Code Review runs on Anthropic's infra and bills separately via usage credits.

If you want the action to run review-as-a-skill but you're on a non-headless setup, it's worth understanding Claude Code headless mode — the same claude -p machinery that powers automation runs. And for a broader take on automated review quality, see code review with Claude.

Frequently Asked Questions

How do I set up Claude Code in GitHub Actions?

Run /install-github-app inside Claude Code as a repo admin — it installs the Claude GitHub App, adds your secret, and drops an example workflow into .github/workflows/. Or do it manually: install github.com/apps/claude, add ANTHROPIC_API_KEY to your repo Actions secrets, copy an example workflow into .github/workflows/, and tag @claude in a PR or issue to test.

What permissions does the Claude Code workflow need?

Least privilege is contents: write, pull-requests: write, and issues: write, plus id-token: write only if you authenticate through OIDC for a cloud provider. The Claude GitHub App itself requests Contents, Issues, and Pull requests read & write. By default only users with write access can trigger the action, and bots are blocked.

Will Claude merge or open pull requests by itself?

No. Claude commits to a new branch and returns a link to the GitHub PR-creation page — you click it to open the PR. Anthropic's managed Code Review check run also always completes with a neutral status, so it never auto-blocks or auto-approves a merge.

Is it safe to run Claude on pull requests from forks?

Be careful. pull_request_target and workflow_run run with your base repo's secrets. Never check out the untrusted PR head SHA to the workspace root before the action runs. Either check out the base branch with no ref:, or put the PR code in a subdirectory and pass --add-dir. The action also sanitizes hidden prompt-injection payloads (HTML comments, invisible characters, hidden attributes) by default.

How do I control Claude Code GitHub Actions costs?

Set --max-turns in claude_args (default is 10), add a workflow-level timeout-minutes, use GitHub concurrency to cap parallel runs, and scope @claude commands narrowly. Watch both lines: API token spend and GitHub Actions runner minutes. For managed Code Review, set a monthly spend cap in admin settings and prefer "once after PR creation" over "after every push."

Why don't Claude's commits trigger my CI?

Commits pushed by the default GITHUB_TOKEN (the Actions user) do not trigger downstream CI workflows — that's a GitHub safeguard against recursive runs. Use the Claude GitHub App or a custom GitHub App token via actions/create-github-app-token@v2 so Claude's commits trigger your test suite.

Do I need to upgrade my old @beta workflow?

Yes, if you want it to keep working. @v1 is a breaking change: change @beta to @v1, delete the mode: field (now auto-detected), rename direct_prompt to prompt, and move max_turns, model, custom_instructions, and allowed_tools into claude_args (for example --max-turns 10 --model claude-sonnet-4-6). Old @beta YAML copied from older tutorials fails on the current action.

Wrapping Up

The fastest path is /install-github-app, then a comment-triggered @v1 workflow with the three-permission block and your ANTHROPIC_API_KEY referenced as a secret. Add the scheduled or pull_request automation job when you want unattended reviews. Keep the trigger restricted to write-access users, never check out untrusted fork code to the workspace root, and leave show_full_output off on public repos.

On billing: as of June 16, 2026, GitHub Actions usage still draws from your normal Claude subscription limits — the June 15 credit-pool split was paused. Don't trust pre-June-15 posts that say otherwise; check support article 15036540, which now leads with the pause. And remember you always pay GitHub for runner minutes regardless.

Start with one comment-triggered workflow on a low-traffic repo, watch the first few runs, then add automation once you trust the behavior.

Posted by @speedy_devv