← Back to Blog

Claude Code in GitHub Actions: Workflow Setup, Secrets, Permissions, and Automated PR Review

(Unofficial)

This guide is independently community-maintained. It is not affiliated with, endorsed by, or sponsored by the vendor of the third-party tool it covers. All third-party trademarks are the property of their respective owners.

November 12, 2026
Claude Code in GitHub Actions: Workflow Setup, Secrets, Permissions, and Automated PR Review

Claude Code in GitHub Actions

TL;DR: The official action anthropics/claude-code-action@v1 is GA, and the most useful inputs have been consolidated into three: prompt (a unified instruction), anthropic_api_key (your key), and claude_args (CLI flags). The smallest usable workflow is about twenty lines: comment-triggered, plus a repository secret, plus three permissions. This guide gives you a workflow you can copy as is, how to configure secrets, how to write least-privilege permissions, what an automated PR review looks like, and the six most common failures with the fix for each.

1. Two Integration Shapes: Humans Ask It, or It Runs Itself

TL;DR: Comment-triggered means "someone @claude in a PR"; event- or schedule-triggered means "it runs as soon as the PR opens". The first has the smallest permission surface and the easiest debugging; the second saves the most labor and is the one that needs cost control.

There are two common ways to run Claude Code on GitHub Actions, and which one you pick decides what your workflow looks like:

  1. Comment-triggered (issue_comment / pull_request_review_comment) — whoever @claude's in an issue or PR comment starts a conversation. This suits "ask it a question on demand" and "have the bot explain this diff". It is the starting shape the official docs recommend.
  2. Event- or schedule-triggered (pull_request / schedule) — every PR is reviewed automatically as soon as it opens, or a daily report is generated at 9am. This suits "every PR has to be looked at" and periodic reporting. This route burns tokens continuously, so it must ship with --max-turns and a workflow timeout.

The mistake beginners make is turning both on at once and letting the bill teach the lesson. Get one comment-triggered run working first, then decide whether you want automated review. If Claude Code still does not run locally, wire up the local path first via developer mode and the API proxy, then come back and configure the workflow.

2. The Minimal Workflow (Copy It as Is)

TL;DR: Below is the smallest comment-triggered version. Drop it into .github/workflows/ and it runs; swap the secret name for your own.

yaml
name: Claude Code

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

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  claude:
    # Only run when @claude is actually mentioned, so every comment does not burn tokens.
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Answer the question in this comment. Read the repository files when you
            need to confirm a fact, write the conclusion clearly, and give change
            suggestions as concrete file paths.
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"

Three points: prompt is the unified instruction entry point (since v1 you can write the task there even without an @claude mention); claude_args carries the CLI flags (--max-turns, --model, --append-system-prompt all live there); and anthropic_api_key is read only from a secret — never write your key into the workflow file. If you use a subscription account, switch the secret to CLAUDE_CODE_OAUTH_TOKEN and the input to claude_code_oauth_token.

3. How to Configure Secrets: The Key Goes Into Repo Settings, Not Into Code

TL;DR: Store the key as a repository secret (Settings → Secrets and variables → Actions) and reference it in the workflow as ${{ secrets.XXX }}. A key written into the repository is a leak.

The official setup path comes in two flavors:

  • The quick path: run /install-github-app in your local Claude Code and follow the prompts to install the GitHub App and create the secrets it needs. This requires you to be a repository admin.
  • The manual path: install the Claude GitHub App (repository permissions: Contents read and write, Issues read and write, Pull requests read and write) → add ANTHROPIC_API_KEY to the repository secrets → copy the official example workflow into .github/workflows/.

Both paths share the same property: the key exists only in GitHub's secret store. What the repository shows is a reference, never the value. Rotating the key means replacing it once in the secrets panel; historical runs are unaffected. Client configuration (base URL, key field) can be generated with the client config generator, and the resulting values go into the repository secret.

4. Least Privilege: Getting the Three permissions Right

TL;DR: Declare a permissions: block explicitly instead of inheriting the default token's broad access. Claude only needs issues: write and pull-requests: write to post its conclusion back.

The GITHUB_TOKEN a workflow gets by default may be broader than you expect, or narrower. Rather than guessing, declare the minimum set explicitly at the top of the workflow:

yaml
permissions:
  contents: read        # read code
  pull-requests: write  # post review comments
  issues: write         # reply in issue comments

For read-only use, contents: read is enough. But as soon as Claude has to post its conclusion back to a PR or an issue, you must grant pull-requests: write / issues: write — missing one typically shows up as "the comment never appeared" rather than as an explicit error. The official security guidance says the same thing: restrict the action's permissions to what it needs, and have a human review Claude's suggestions before merging.

Two hard checks on the trigger side fail outright rather than warning you: the triggering user needs write access to the repository — on issue and PR events, a trigger without write access will not start (schedule triggers skip this check; to allow specific users without write access, set allowed_non_write_users and supply your own github_token); and the triggering actor must be a human — bot accounts are rejected unless you list them in allowed_bots. Scheduled jobs hit the second rule most often, because GitHub attributes a scheduled run to whoever last changed the cron.

5. Automated PR Review: Send the Conclusion Back to the PR

TL;DR: Switch the trigger to pull_request, use prompt to state the review dimensions, and use claude_args to cap turns and pick the model. The conclusion lands on the PR as review comments.

yaml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this PR: read the diff first, then look for problems along
            correctness, security, and performance. For every finding give the
            file path and line number, and skip style-preference suggestions.
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"

The trade-off that matters here is --max-turns: it caps how many steps (tool-call rounds) Claude may take on its own, and it is the most effective cost gate in CI. Lower it to make the agent more restrained, raise it to let it look closer — but re-weigh the budget every time you raise it. The review methodology itself (how to define review criteria, how to divide work between human and machine) is out of scope here; see the governance article in "Related Reading" below.

6. Six Common Failures and How to Fix Them

TL;DR: Mixed-up input names, missing permissions, missing secrets in fork PRs, a doubled /v1 in the base URL, a model id that does not exist, and runaway runs — one fix for each.

  1. You copied the beta input names. In v1, mode / direct_prompt / custom_instructions / max_turns have been consolidated into prompt and claude_args (--max-turns and --append-system-prompt go inside claude_args). The old forms no longer have any effect.
  2. Comments do not get posted. Most of the time permissions is missing pull-requests: write or issues: write. Declare the permissions: block explicitly; do not rely on the default token.
  3. The key is unavailable in a forked PR. GitHub does not inject secrets into fork PRs by default — that is a protection mechanism, not a bug. Either move the review to a comment trigger, or write "do not review fork PRs" as an explicit condition.
  4. The base URL has an extra /v1. The client appends /v1/messages itself, so one extra segment gives you a 404.
  5. The model name does not exist. The value of --model must be a real upstream model id. A wrong value usually errors out or silently falls back to the default model without telling you.
  6. It ran away. Nobody is watching in CI: add --max-turns, add a workflow-level timeout-minutes, and use GitHub's concurrency to limit parallel runs on the same branch.

7. Controlling CI Cost: Three Gates

TL;DR: Tokens are billed by usage, and CI is where that runs away. Setting three gates — turns, concurrency, and timeout — keeps the cost of one review within a predictable range.

  • The turns gate: --max-turns directly determines how many tool-call rounds a single run may take. It is the most effective knob.
  • The concurrency gate: when several PRs open in the same repository they all run at once. Use concurrency to serialize per branch and avoid spikes.
  • The timeout gate: a workflow-level timeout-minutes is the backstop, so one agent cannot burn the whole quota on a single PR.

One rule of thumb on top of that: validate "key, permissions, model" with a comment trigger first, then turn on automated review. Do it the other way around and you end up debugging configuration errors and cost problems at the same time.

8. Point CI at the Same Gateway: One Key for Local and CI

TL;DR: Point ANTHROPIC_BASE_URL at CodeGateway and use the same key. Switching models in CI needs no new process, and the usage is visible on the dashboard.

If you already run local Claude Code through CodeGateway, CI can point at the same gateway:

yaml
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.CODEGATEWAY_API_KEY }}
          prompt: "Review this PR and list correctness problems with file paths."
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"
        env:
          ANTHROPIC_BASE_URL: https://api.codegateway.dev
          ANTHROPIC_AUTH_TOKEN: ${{ secrets.CODEGATEWAY_API_KEY }}

Three points: ANTHROPIC_BASE_URL must not carry a /v1 suffix (the client appends /v1/messages itself); ANTHROPIC_AUTH_TOKEN takes your CodeGateway key, the same key you pass to the anthropic_api_key input; and --model must be a model id that actually exists in the gateway's catalog.

The value comes in three layers: one key reaches both your laptop and CI, so you do not have to apply for a separate official account for CI; under the same key you can pick the model per scenario (Sonnet for routine reviews, Opus for the hard ones) by changing --model rather than the pipeline; and the input and output tokens of every run land in the workspace's usage and logs, so what CI costs and which PR cost the most are both obvious on the dashboard. To be explicit, CodeGateway bills on top of the official price according to its plan tier; the exact multiplier is published on the pricing page.

Get a Key Now

No official key, or you would rather not bind a foreign card? ⇒ Get one at CodeGateway: sign up and start using it right away — one key reaches Claude / GPT / Gemini and other model families, usage is billed per token, the balance is visible, and swapping in your own key in CI is a one-line secret change. Create your account to go straight to the register page. Registration and billing details are on the pricing page.

Author:CodeGateway TeamReviewed on:2026-11-05

Solve API Key & Billing limits with CodeGateway

Lacking an official API key or facing overseas card payment issues? Create an sk-cg- key instantly. One key for Claude, GPT, Gemini, and DeepSeek: Claude and Gemini text models use the Anthropic Messages protocol (/v1/messages) — the OpenAI-compatible text endpoints do not accept them. Built-in smart routing and free trial credits included.

Sign up free