ClaudeMap

·Skills & Commands

Wire Claude Code into GitHub Actions — @claude mentions, PR reviews, cron triggers, auth and permissions, fork-PR secrets behavior, copy-pasteable workflow templates, plus four cost-operations levers and an org-level rollout governance checklist.

Claude Code in GitHub Actions: @claude Mentions, PR Reviews, and Scheduled Automation

Claude Code's GitHub Actions integration is a first-class citizen from Anthropic. It puts Claude directly in issue comments, PR reviews, and scheduled jobs — not just your local terminal. As of 2026, Anthropic has promoted Claude Code to a default GitHub App install path and ships claude-code-action for direct workflow use. This guide covers the three most useful trigger modes (@claude mentions, automated PR review, scheduled sweeps), three authentication methods (API key, OAuth, OIDC), the four required permissions, and copy-pasteable workflow templates you can ship today.

TL;DR

  • Three trigger modes: @claude mention / automated PR review / cron-scheduled sweep
  • Three auth methods: API key (simplest), OAuth (multi-user), OIDC (recommended for Bedrock/Vertex IAM)
  • Official action: anthropics/claude-code-action@v1 — the GitHub App default install path
  • Five required permissions: contents: read / issues: write / pull-requests: write / id-token: write / actions: read
  • 2026 gotchas: @claude must be lowercase and @ immediately precedes the name; fork PRs cannot access secrets; OIDC needs correct IAM role trust

GitHub App install vs hand-written workflow

There are two ways to wire Claude Code into your repository.

The first path runs /install-github-app from the repo root:

> /install-github-app

Claude Code walks you through OAuth and installs the Anthropic GitHub App on the target repository. This path only requires repo admin permissions, scopes minimally, and is the right starting point for first-time setup. Once installed, anthropics/claude-code-action runs as the GitHub App — all secrets are managed by the App and your repo settings never expose a raw ANTHROPIC_API_KEY.

The second path is a hand-written workflow file under .github/workflows/ that uses anthropics/claude-code-action@v1. You configure secrets, permissions, and triggers yourself. Use this for custom requirements — allow-lists, cron-only triggers, running on forks, or any flow the App path doesn't cover. Both paths can coexist: the App handles @claude mentions in comments while a hand-written workflow handles nightly sweeps.

The GitHub App path needs repo admin permissions; the hand-written workflow path only needs contents:write. Either way, set an allowed_users allow-list so anonymous users can't trigger Claude.

Three trigger modes

Ranked by how often you'll reach for them.

Mode 1: @claude mention (human-in-the-loop)

Fires when someone writes @claude ... in an issue comment or PR review comment. This is interactive mode — Claude reads context, calls tools, edits files, runs tests, and replies. Use it for: fixing bugs, answering questions, filling in docs, small refactors.

Mode 2: PR opened / synchronized (automated review)

Every time a PR opens or a new commit lands, Claude reviews it, leaves inline comments, and posts a summary. Use it for: enforcing a team review checklist, catching style issues and missing tests, flagging common pitfalls.

Mode 3: cron scheduled sweep

A schedule: trigger that runs Claude on a cadence — daily or weekly — to scan issues, check CI failures, or generate reports. Use it for: long-tail maintenance work humans forget to do.

Below are three copy-paste workflows. First, the @claude mention workflow:

# .github/workflows/claude-mention.yml
name: Claude mention
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
      actions: read
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: claude_mention
          # Optional: restrict who can trigger
          allowed_users: "octocat,monalisa"

trigger: claude_mention is the key field — only comments containing @claude ... wake the action. Anything else is silently skipped, no quota burned.

PR review mode

Note: the prompt: field in the YAML below is claude-code-action's input field (a plain GitHub Actions string), not a Claude API prompt template. Its text is passed verbatim to Claude as the task description.

# .github/workflows/claude-pr-review.yml
name: Claude PR review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: pr_review
          # Custom review prompt
          prompt: |
            Review this PR against this checklist:
            1. Did it break any existing API contract?
            2. Is there a test for each new code path?
            3. Are there unhandled console.log / debugger statements?
            4. Performance and concurrency safety?
            Write findings as inline review comments.

Note contents: read here, not write — review mode is read-only by design. Promote contents to write if you want Claude to fix issues it finds.

Cron scheduled sweep mode

Same as above: prompt: is an action input string passed verbatim to Claude as the task description.

# .github/workflows/claude-nightly.yml
name: Claude nightly sweep
on:
  schedule:
    - cron: "0 9 * * 1-5"   # weekdays at 09:00 UTC

jobs:
  sweep:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: schedule
          prompt: |
            Scan issues and PRs from the last 24 hours:
            - Find issues with no response for over 3 days
            - Find PRs with failing CI
            - Write the result to issues/nightly-report-<date>.md and post a summary

cron uses UTC in GitHub Actions. Convert from your local timezone directly in the cron expression (Beijing 17:00 = UTC 09:00).

Required permissions

Reading the three snippets above, four permission sets are always required — any missing permission causes a job to fail on first run:

| Permission | Why Claude needs it | What happens without it | |---|---|---| | contents: write | Commit fixes and edits | Bug-fix mode fails immediately | | issues: write | Reply on issues | @claude mentions can't reply | | pull-requests: write | Post inline PR comments | PR review produces no output | | id-token: write | OIDC token exchange | Bedrock / Vertex / Foundry backends can't authenticate | | actions: read | Read CI status for decisions | Cron sweeps can't see build results |

pull-requests: write is the one most often forgotten — it's the permission to comment on a PR, not to merge one. The name is misleading.

Three authentication methods

Claude Code action needs an Anthropic credential to run. Three options, each with a clear best-fit:

Method 1: ANTHROPIC_API_KEY (simplest)

Add an ANTHROPIC_API_KEY secret in repo Settings → Secrets. The action reads it by default. Good for personal repos, small teams, low-frequency use. Downside: long-lived credential; you have to rotate manually if it leaks.

Method 2: CLAUDE_CODE_OAUTH_TOKEN (officially recommended)

Authorize once through claude-code-action OAuth. The GitHub App install path uses this by default. Short-lived tokens that auto-rotate. Downside: awkward to share across many repos.

Method 3: OIDC (cloud backends + Bedrock/Vertex/Foundry)

- uses: anthropics/claude-code-action@v1
  with:
    trigger: claude_mention
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    # AWS Bedrock
    use_bedrock: true
    aws_region: us-east-1
    # or GCP Vertex
    use_vertex: true
    gcp_project_id: my-gcp-project
    gcp_region: us-central1

The id-token: write permission combined with the cloud provider's OIDC trust policy lets GitHub Actions mint short-lived cloud credentials directly — no long-lived API key. Use it for: enterprise environments, strict compliance, AWS/GCP billing.

Security: allowed_users and bot filtering

In @claude mention mode, anyone with write comment access on the repo can trigger Claude. That includes granted collaborators, CI bots, and external contributors with "Allow edits from maintainers" enabled — and every trigger burns tokens.

Two rules minimize the blast radius:

  1. Set an allowed_users allow-list. Comma-separated GitHub usernames. Mentions from anyone outside the list are silently dropped.
  2. Filter anonymous comments. Reject any comment where github.event.comment.author_association == "NONE" — this blocks anonymous users and fork PR comments.
- uses: anthropics/claude-code-action@v1
  with:
    trigger: claude_mention
    allowed_users: "octocat,monalisa,dependabot[bot]"
    # auto-filter NONE (anonymous / fork) comments

How secrets behave on fork PRs

A classic GitHub Actions gotcha: PRs from forks run workflows but don't get parent-repo secrets. They're two separate decisions — workflows run for security, secrets stay in the parent repo for security. For Claude Code action this means:

  • PRs from forks: the action triggers but ANTHROPIC_API_KEY is unavailable; @claude mentions fail silently.
  • Workaround: use pull_request_target for fork PRs (but mind prompt injection), or restrict triggers with allowed_users so only trusted contributors can wake Claude.
on:
  pull_request_target:   # note: *_target, behaves differently
    types: [opened]

pull_request_target runs the workflow in the parent repo's context, so secrets are available, but the code is still from the PR — a classic prompt injection entry point. Not recommended without sandboxed Claude dialogs.

Debugging checklist

When Claude Code action doesn't fire, walk through this list:

  1. Read the action log — failed jobs usually print Claude's raw error. The two most common are auth errors and permission errors.
  2. Check workflow run permissions — Settings → Actions → General → "Workflow permissions". If it's Read-only, your contents: write is silently ignored.
  3. Verify the trigger string — @claude must be lowercase, @ directly before the name, and the name must match the action's default trigger username. @Claude (capital C) won't fire.
  4. Check allowed_users spelling — GitHub usernames are case-sensitive; Octocat and octocat are different accounts.
  5. Network issues — Bedrock/Vertex modes fail on missing id-token: write permission first, then on IAM roles not bound to the GitHub OIDC provider.
  6. Quota exhaustion — API key mode returns 429 when the Anthropic account runs out. OAuth mode rotates tokens automatically, but if the OAuth link is revoked you need to rerun /install-github-app.

Common pitfalls

Pitfall 1: assuming the GitHub App installs workflows. The App handles credentials — it doesn't auto-create workflows. You still need .github/workflows/ files calling anthropics/claude-code-action@v1.

Pitfall 2: hardcoding secrets in workflow files. ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} is fine; hardcoding the key value is not — once a PR exposes it, anyone can read it.

Pitfall 3: forgetting cron is UTC. GitHub Actions cron runs in UTC. 0 9 * * * is UTC 09:00, not 09:00 in your local timezone.

Pitfall 4: Claude failing silently on fork PRs. Default behavior is to fail without surfacing the error — easy to mistake for a configuration problem. Look for secrets are not available to forks in the log.

Pitfall 5: long prompts pasted in PR comments. @claude mention prompts come from the comment body — anyone can write them. Prompt injections like @claude rm -rf / are a real risk. The allowed_users allow-list is the only reliable defense.

A complete team-ready workflow

Combining everything above, here's the everyday team workflow: @claude mention + automated PR review + weekday cron sweep, all in one bundle.

# .github/workflows/claude.yml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  pull_request:
    types: [opened, synchronize, ready_for_review]
  schedule:
    - cron: "0 9 * * 1-5"

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: ${{ github.event_name == 'schedule' && 'schedule' || github.event_name == 'pull_request' && 'pr_review' || 'claude_mention' }}
          allowed_users: "your-team,dependabot[bot]"
          # Per-mode prompt overrides live here if needed

Three triggers in one file. The trigger: value picks based on which event fired: schedule for cron, pr_review for PR events, claude_mention for comments. This is the shortest path from "we want Claude in our CI" to "Claude is in our CI".

Cost Operations: Keeping the @claude Bill Predictable

Every @claude trigger burns real tokens; the gap between "it works" and "it's affordable" is operations. Four levers, ordered by how fast they pay off:

Concurrency cancellation. Add concurrency: to the job (new runs in the group cancel older ones) — when a PR gets five pushes in a row, only the latest runs. One line, roughly half the bill; make it the team default.

Narrow the triggers. allowed_users already blocks strangers; going further with label-gating (only issues/PRs labeled claude fire) filters out drive-by mentions. Start cron jobs at once a day and increase only after the value is proven.

Put the context on a diet. Token consumption tracks prompt size and tool calls: a giant CLAUDE.md or repo-wide attachments inflate the bill directly. For CI, maintain a lean dedicated CLAUDE.md (build, test, conventions only) — much cheaper than reusing the interactive session's file.

Reconcile monthly. Give the CI key its own workspace or billing view in the Anthropic Console and reconcile against workflow run counts at month end — anomalies are almost always one PR triggering in a loop or a cron-density mistake, visible at a glance.

Multi-Repo Rollout: An Org-Level Governance Checklist

One repo working is the start; rolling out to dozens is where governance breaks. Six checks before you scale:

  1. Single approval path: the GitHub App's org-level install is held by a few admins — no one adds it to repos casually. Installing it hands that repo an API key.
  2. Workflow changes go through PR review: claude.yml itself must sit behind branch protection — it can change triggers and read secret scopes, which makes it supply-chain-sensitive.
  3. A written secret-rotation policy: rotation cadence, owner, and revocation steps for ANTHROPIC_API_KEY go into the on-call handbook; prefer short-lived OAuth credentials (CLAUDE_CODE_OAUTH_TOKEN) where possible.
  4. Distribute via a template repo: make the proven workflow a template (or an org-level reusable workflow) and copy, don't hand-write — five repos with five claude.yml variants is a debugging nightmare.
  5. Auditable: workflow run history is the audit log; periodically sample who triggered Claude in what context and what changed, cross-read against each repo's allowed_users list.
  6. An exit path: define the downgrade — revoking the App or deleting the workflow is a complete exit; avoid hidden dependencies (someone piping CI results into another workflow).

Frequently asked questions

Do I need to keep ANTHROPIC_API_KEY if I install the GitHub App?

No. The App path uses OAuth short-lived tokens managed by Anthropic's GitHub App — your repo never sees a raw API key. If you later add hand-written workflows for cron sweeps, you can keep either: API key in repo secrets, or OAuth via CLAUDE_CODE_OAUTH_TOKEN. Pick OAuth if you have any compliance or rotation requirements.

Can Claude Code action run on a PR from a fork?

Yes, but it won't have access to the parent repo's secrets. The action still triggers; Claude just can't authenticate to Anthropic, so the run fails silently. The safe pattern is either (a) restrict triggers with allowed_users so only repo members can fire it, or (b) use pull_request_target and accept the prompt-injection risk. For most teams, option (a) is correct.

What's the difference between the GitHub App and the claude-code-action workflow?

The GitHub App is a credential broker — it handles OAuth, token rotation, and per-repo scoping. The action (anthropics/claude-code-action@v1) is the code that runs in your workflow. The App path implicitly invokes the action; the hand-written workflow path lets you call the action with custom triggers, prompts, and permissions. They overlap but aren't redundant.

How much do GitHub Actions invocations cost?

Each successful Claude Code action run consumes Anthropic tokens based on the prompt and tool calls — roughly comparable to running Claude Code locally with the same task. Failed runs (auth errors, missing permissions) don't consume tokens. To keep cost predictable: set allowed_users so random comments don't trigger Claude, and use concurrency: on the job to cancel older runs when a new one starts.

Can I use Claude Code action with self-hosted runners?

Yes. Set runs-on: self-hosted and the action will run on your own runners. The Bedrock / Vertex OIDC path is especially common on self-hosted runners inside AWS / GCP, since the runner can already assume the cloud role. Just make sure your runners have network access to api.anthropic.com (or the Bedrock / Vertex endpoint you're using).

Official references

This guide is current as of August 2026. Workflow syntax and Claude Code action flags evolve; pin to a major version (e.g. @v1) rather than @main to keep CI stable.