Claude Code GitHub Actions: Secure Setup Guide (2026)

Claude Code GitHub Actions can do much more than review pull requests—but the safest setup is not the most permissive setup. A workflow that can read code, respond to comments, push commits and inspect CI logs is an agent with real repository authority. The right question is therefore not only “How do I install it?” but what should it be allowed to do, who can trigger it, and what must still require a human?

This guide builds a security-first Claude Code GitHub Actions setup in two stages: start with a read-only review workflow, then add a separate write-capable workflow for explicit @claude requests. The separation makes permissions easier to reason about and gives teams a practical rollback path.

If you are still deciding where Claude Code fits in your development stack, see our Cursor vs Claude Code comparison for the broader editor, terminal, automation and agentic workflow trade-offs.

Methodology: this is a documentation-verified implementation guide based on current Anthropic and GitHub documentation checked September 18, 2026. AI-XBlog is not claiming that every example below was production-tested in your repository. GitHub plans, repository rules and Claude Code behavior can vary, so validate the workflow in a non-critical repository before broader rollout.

The safe default: separate review from code-changing automation

Anthropic currently offers two distinct paths for GitHub-based code review and automation. Claude Code Review is a managed review product for Team and Enterprise organizations. Claude Code GitHub Actions is the configurable workflow integration that can respond to mentions, run scheduled jobs and perform repository work.

Use case	Safer starting point	Why
Automatic PR findings	Managed Code Review or a read-only Action	Review can stay non-mutating
Answer questions about a PR	Read-only Action	Repository context without write authority
Implement a requested change	Separate interactive Action	Write permissions exist only where needed
Scheduled reports	Read-only automation workflow	No reason to grant code-writing access to a report job
Issue-to-code automation	Write-capable Action behind trusted triggers	Agent can work, but the merge remains governed by branch rules

If all you need is PR feedback, do not begin by granting contents: write. Start with review-only permissions. Add a second workflow only after you have a concrete task that needs repository mutation.

Before you start

Repository admin access for the initial Claude GitHub App / workflow setup.
GitHub Actions enabled on the repository.
Either an Anthropic API key, a supported Claude subscription token, or an organization-level workload identity setup.
A non-critical repository or test branch for your first rollout.
Branch protection or a ruleset on the default branch before enabling write-capable agent workflows.

Anthropic documents two setup routes. The quick route is /install-github-app from Claude Code. The manual route installs the Claude GitHub App, adds an authentication secret, and places a workflow under .github/workflows/. Both require repository admin access.

Step 1: choose the authentication model

Authentication	Good fit	Security / operations note
Anthropic API key	Teams that want API billing and centralized ownership	Store only in GitHub Secrets; rotate like any production credential
Claude subscription OAuth token	Individual or smaller setups already using an eligible Claude plan	Tied to the person/subscription that created it; weaker choice for shared organization infrastructure
Workload identity federation	Organizations that want to avoid a long-lived Anthropic secret	Uses GitHub OIDC to exchange for Claude API access; requires `id-token: write` and Anthropic Console configuration

Never put an API key or OAuth token directly in the YAML file. Use GitHub Secrets and pass the secret to the action input. For organization-wide deployment, Anthropic recommends an organization-owned API key or workload identity federation rather than a personal OAuth token.

Step 2: start with a read-only PR review workflow

The first workflow should prove three things before the agent can change code: the integration can authenticate, Claude can read the repository context, and your trigger/permission model behaves as expected.

name: Claude read-only review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write

    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - 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 }}"

This pattern keeps the GitHub token read-only for repository content and PR metadata. It also gives the job a hard timeout. Anthropic’s documentation notes that public-repository fork pull requests do not receive repository secrets, so a secret-authenticated review workflow may not run for those forks. Treat that as a security boundary, not a bug to bypass casually.

Step 3: validate the read-only boundary

Open a small test PR from a branch in the same repository.
Confirm the workflow starts only on the events you configured.
Inspect the job permissions in the Actions run.
Confirm the action can analyze the PR but does not have contents: write.
Confirm no secret value appears in logs.
Keep show_full_output off unless you have a controlled debugging reason.

Anthropic disables full output by default because tool results, file contents and command output can expose credentials or other sensitive material. GitHub also warns that secret redaction is not a complete substitute for least privilege.

Step 4: add a separate write-capable @claude workflow

Only after the read-only workflow behaves correctly should you add an interactive workflow that can implement changes. Keep it separate so the permission difference is visible during review.

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

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    timeout-minutes: 20

    permissions:
      contents: write
      pull-requests: write
      issues: write
      actions: read
      id-token: write

    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: |
            --max-turns 8

Anthropic’s action performs actor checks before Claude starts. For issue and pull-request events, the triggering user normally needs write access to the repository. Bot actors are rejected unless explicitly allowed. Those checks are useful guardrails, but they do not replace GitHub workflow permissions or branch protection.

The permission budget: grant capability per workflow, not per product

A common mistake is to copy the most permissive example and reuse it for every automation. Instead, treat every workflow as a separate permission budget.

Permission	Grant when	Do not grant merely because
`contents: read`	Claude must inspect repository files	The action is installed
`contents: write`	Claude must commit code changes	You only want review or reporting
`pull-requests: write`	Workflow must update PR-related data	The workflow runs on a PR
`issues: write`	Claude must post or modify issue content	You only need issue context
`actions: read`	Claude needs CI status/log information	You already have repository read access
`id-token: write`	Required by the default GitHub App/OIDC authentication path	You want general write access

If you allow extra CLI tools, apply the same rule. Anthropic documents --allowedTools for adding specific capabilities. Prefer narrow command patterns over broad shell access. A report job usually does not need arbitrary Bash. A test workflow might need only a specific package-manager test command.

Do not casually bypass the write-access trigger check

The action’s allowed_non_write_users option exists, but Anthropic describes it as risky because it bypasses the primary write-access gate. If you use it, keep the workflow permissions extremely narrow, pass the job-scoped GITHUB_TOKEN rather than a long-lived personal token, and restrict allowed tools to the minimum required.

For a public repository, allowing all non-write users or all bots can turn untrusted comments into agent-controlled input. That is exactly the kind of boundary where prompt injection becomes an operational risk rather than a theoretical model problem.

Be especially careful with pull_request_target and workflow_run

pull_request_target and some workflow_run patterns execute in a privileged base-repository context where secrets can be available. GitHub and Anthropic both warn against checking untrusted pull-request code into the workspace root before the agent runs.

Prefer the base ref in the workspace root.
If you must inspect an untrusted PR head, isolate it from the trusted working tree.
Keep token permissions at least privilege.
Do not expose unnecessary repository or organization secrets.
Do not assume agent prompt filtering makes untrusted code safe.

This is where the broader principles in our AI Agent Security guide apply directly: untrusted data must not silently gain authority over tools, credentials or deployment paths.

Keep branch protection as the real merge gate

Agent-generated commits should not be equivalent to an approved production change. Protect the default branch so GitHub—not the model—enforces the final policy.

Require a pull request before merging.
Require at least one human approval for consequential repositories.
Require status checks to pass.
Consider CODEOWNERS for sensitive paths.
Consider dismissing stale approvals when new commits change the reviewed diff.
Prevent force pushes and deletion on protected production branches unless your workflow genuinely needs them.

GitHub branch protection can require reviews, status checks, code-owner approval and additional restrictions. The key architectural idea is simple: Claude may propose and commit; repository policy decides whether the change can merge.

Cost controls: cap the agent loop as well as permissions

Claude Code GitHub Actions consume both GitHub Actions runner time and Claude usage. Anthropic recommends specific prompts, concise repository instructions, --max-turns, workflow timeouts and concurrency controls. For the subscription-versus-API cost model behind that usage, see our Claude Code Pricing in 2026 guide.

concurrency:
  group: claude-${{ github.ref }}
  cancel-in-progress: true

jobs:
  claude:
    timeout-minutes: 20
    # ...
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--max-turns 8"

The exact turn and timeout limits depend on repository size and task complexity. The important part is that “unattended” does not mean “uncapped.”

Authentication choice also changes cost accounting

With an Anthropic API key, model usage is billed through the API account. With a Claude subscription OAuth token, Anthropic documents that runs use the connected subscription instead of API billing. For current plan details and Anthropic’s current Agent SDK usage rules—including the paused June credit change—see our Claude Pricing guide.

A safer rollout sequence

Phase	Agent authority	Exit condition
1. Read-only review	Read repository and PR context	Triggers, auth and logs behave as expected
2. Trusted interactive writes	Write code only when a trusted maintainer explicitly requests it	Branch rules block unreviewed merge paths
3. Narrow automation	Run a specific scheduled/event task with limited tools	Cost and failure behavior are observable
4. Broader autonomy	Only permissions justified by measured workflow value	Security review covers untrusted inputs, secrets and rollback

This follows the autonomy principle from our AI Agents guide: increase agent authority only when runtime choice creates enough value to justify the added risk and evaluation burden.

Pre-production checklist

The workflow contains no literal API key, OAuth token or personal access token.
Each workflow has only the GitHub permissions it needs.
Write-capable workflows are separate from read-only review workflows.
allowed_non_write_users is off unless there is a documented exception.
allowed_bots uses an explicit allowlist if bots must trigger Claude.
Untrusted PR code is not checked out into a privileged workspace root.
The default branch requires PR review and required status checks.
Agent runs have a timeout and a turn/cost cap.
Full output/debug logging is disabled for normal production runs.
Someone owns credential rotation, workflow review and incident rollback.

Common troubleshooting

Claude does not respond to @claude

Check that the GitHub App is installed, Actions are enabled, the authentication secret exists, the trigger phrase contains @claude as a complete word, and the actor has repository write access unless you intentionally configured an exception.

OIDC or authentication fails

For the default GitHub App / OIDC path, confirm the workflow grants id-token: write. If you use an API key or OAuth token, verify the secret is valid without printing it to logs.

CI does not run on Claude’s commits

Anthropic notes that commits made with GitHub’s default GITHUB_TOKEN do not trigger additional workflow runs. If you explicitly pass that token to the Claude action, understand the tradeoff before changing authentication just to trigger downstream automation.

Claude needs CI logs

Add actions: read to the workflow permissions and configure the action’s additional permissions for GitHub Actions access. Do not grant workflow write access merely to read test failures.

Frequently asked questions

Is Claude Code GitHub Actions the same as Claude Code Review?

No. Code Review is a managed review product. Claude Code GitHub Actions is a configurable workflow integration that can respond to mentions or run automated tasks. Use the managed review path when review is all you need; use Actions when you need custom triggers or repository work.

Can anyone comment @claude and make it change my repository?

By default, the action checks that the triggering actor has write access on issue and pull-request events, and it rejects bot actors unless allowed. Do not weaken those checks without reducing workflow authority accordingly.

Should I use pull_request_target?

Only when you understand why you need the privileged base-repository context. If it is necessary, follow GitHub and Anthropic guidance for untrusted refs, minimum token permissions and secrets. A standard pull_request workflow is usually easier to reason about for review-only jobs.

Can Claude merge directly to main?

Your repository policy should prevent an agent-generated change from bypassing the human and CI gates you require. Protected branches or rulesets should remain the authority for merge requirements.

Bottom line

The best Claude Code GitHub Actions setup is not one giant workflow with every permission. Use a read-only review workflow first. Add write access in a separate interactive workflow. Keep untrusted actors outside the write boundary, use GitHub Secrets or short-lived identity, cap turns and runtime, and let branch protection remain the final merge gate.

That structure makes the integration easier to audit, cheaper to run and easier to disable when something behaves unexpectedly.

Primary sources

AI-XBlog Weekly Brief

Keep up with AI that actually works

Join the AI-XBlog Weekly Brief for major AI updates, practical workflows, useful tools, and editor’s picks. No daily noise.

Reader discussion

Join the discussion

Have you tried this tool or workflow? Share your experience, corrections, or questions. Useful reader feedback may help us improve this article.

All comments are reviewed before publication. Your email address will not be published. Promotional links and low-value spam are removed.

Claude Code GitHub Actions in 2026: A Security-First Setup Guide