Claude Code GitHub Actions Setup: @claude Mentions, Workflows, Secrets and Costs (2026)

Claude Code GitHub Actions lets you type @claude in any issue or pull request and have Claude read the code, make changes and push commits. It runs inside your normal GitHub workflows.

This guide covers the one-command setup, the manual setup, workflow examples, secrets, Bedrock and Vertex, costs and the security settings you should not skip.

What Claude Code GitHub Actions Does

The Claude Code GitHub Action runs the full Claude Code agent on a GitHub runner. It can analyze code, answer questions, write fixes and open pull requests, all from a comment.

Common jobs it handles

• Issue to PR: “@claude implement this feature based on the issue description”.
• Bug fixes: “@claude fix the TypeError in the user dashboard component”.
• Questions: “@claude how should I add auth to this endpoint?”
• Code review: run a review skill on every new pull request.
• Scheduled reports: a daily summary of commits and open issues.

Note: This is different from Anthropic’s managed Code Review product and from Claude Code on the web. The action is the one you control with your own workflow files.

What You Need Before You Start

• Admin access: you must be an admin on the repository to install the app and add secrets.
• A github.com repo: the quick setup command does not work with GitLab or Bitbucket remotes.
• GitHub CLI: for quick setup, install gh and run gh auth login first.
• Claude Code locally: for quick setup only. See our install guide if you do not have it yet.
• A credential: a Claude API key from the Claude Console, or a paid Claude plan for an OAuth token.

Quick Setup with /install-github-app

This is the easiest path. Claude Code does almost everything for you and ends with a ready-to-merge pull request.

1. Open Claude Code in your repo. Run claude from the repository folder.
2. Run the command. Type /install-github-app and follow the prompts.
3. Install the Claude GitHub App. Approve the app for the repo when prompted.
4. Pick your credential. Claude Code reuses an existing API key, or lets you create a long-lived subscription token or paste a key.
5. Let it save the secret. It stores ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a repository secret.
6. Choose workflows. Pick the @claude workflow, and the review workflow if you want automatic PR reviews.
7. Merge the PR. Claude Code pushes a branch and opens GitHub with the PR ready. Create it, merge it, and @claude is live.

Tip: Press Esc to stop setup partway. Run /install-github-app again later and choose “Update workflow file with latest version” to refresh old workflow files.

Manual Setup

Use this if you do not run Claude Code locally, the command fails, or you want full control over the YAML.

Step 1: Install the GitHub App

Install the official Claude app from github.com/apps/claude. The action needs three of its permissions: Contents, Issues and Pull requests, all read and write.

Step 2: Add a secret

In the repo, go to Settings, then Secrets and variables, then Actions. Add one of these:

• ANTHROPIC_API_KEY: a key from the Claude Console, billed per token.
• CLAUDE_CODE_OAUTH_TOKEN: run claude setup-token locally to generate it. It uses your Pro, Max, Team or Enterprise plan.

Step 3: Add the workflow

Copy examples/claude.yml from the claude-code-action repo into .github/workflows/. It works as-is with the API key secret.

If you used an OAuth token, swap the auth line for claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Rolling out to a whole organization

• App: install the Claude app once at the org level.
• Secret: store the key as an org-level Actions secret. Use an API key here, since an OAuth token is tied to one person’s plan.
• Workflow: add it per repo, or define a reusable workflow that each repo calls.
• No stored secret: use workload identity federation with anthropic_federation_rule_id and anthropic_organization_id, plus id-token: write.

Workflow Examples

Respond to @claude mentions

This is the official interactive workflow. Claude replies in a comment and updates it as it works:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

The id-token: write line is needed for the action’s default GitHub App login. The actions: read line lets Claude read CI results on PRs.

Automatic PR review

This one installs Anthropic’s code-review plugin and runs it when a PR opens or updates. The --comment flag makes Claude post inline comments:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    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 --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Claude skips draft and closed PRs, trivial ones, and PRs it already commented on. Our Claude skills guide explains how to write your own skill for the prompt input.

Daily scheduled report

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - 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 claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

Note: GitHub runs scheduled workflows only from the default branch. In public repos it turns the schedule off after 60 days without activity.

Key Inputs and CLI Arguments

Each input goes under with: in the action step. These are the ones you will use most:

Useful claude_args flags

• --max-turns: caps how many steps Claude takes, which caps cost.
• --model: pick a model, such as claude-sonnet-5 or claude-opus-5-5.
• --allowedTools: grant specific tools in automation mode.
• --mcp-config: load MCP servers. See our Claude Code MCP setup guide.
• --debug: verbose logs when something breaks.

Upgrading from the beta

If a workflow still uses @beta, change it to @v1, delete the mode input, rename direct_prompt to prompt, and move model and max_turns into claude_args.

Using Bedrock, Vertex or Foundry

If your company already buys Claude through a cloud, you can route the action there. All three use OIDC, so no static cloud keys sit in your repo.

Bedrock action step

Add an aws-actions/configure-aws-credentials@v4 step with your role and region first, then:

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_bedrock: "true"
          claude_args: '--model us.anthropic.claude-sonnet-4-6'

Bedrock model IDs carry a region prefix like us.. Use the prefix for the region group where you enabled model access.

Vertex action step

Add a google-github-actions/auth@v2 step with id auth first, then:

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_vertex: "true"
          claude_args: '--model claude-sonnet-5'
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5

Anthropic’s examples use a custom GitHub App with APP_ID and APP_PRIVATE_KEY secrets for the token step. You can use the official app instead and drop the github_token line.

What It Costs

Every run uses two meters. Neither is huge for small jobs, but both add up on busy repos.

1. GitHub Actions minutes

• Public repos: standard GitHub-hosted runners are free.
• Private repos: Linux 2-core runners cost $0.006 per minute. GitHub Free includes about 2,000 minutes a month, and Pro or Team about 3,000.

2. Claude tokens

With an API key, you pay per token. Per Anthropic’s pricing page, Sonnet 5.5 is $2 input and $10 output per million tokens, and Opus 5.5 is $4 and $20.

As simple arithmetic, a run that reads 200,000 tokens and writes 10,000 on Sonnet 5.5 costs about $0.50. Real runs vary a lot with repo size and task.

With a CLAUDE_CODE_OAUTH_TOKEN, runs draw from your subscription instead of API billing. Our Claude Code pricing guide compares the plans.

How to keep costs down

• Cap turns: add --max-turns 5 or similar to claude_args.
• Set timeouts: use timeout-minutes on the job.
• Limit parallel runs: use GitHub’s concurrency setting.
• Keep CLAUDE.md short: Claude reads it on every run.
• Write clear requests: specific @claude comments need fewer turns.

Security Best Practices

You are giving an agent write access to your code. A few defaults protect you, and a few settings are up to you.

Built-in protections

• Write access check: on issue and PR events, the person who triggers Claude must have write access. Override only with allowed_non_write_users.
• No bot loops: bot actors are rejected unless listed in allowed_bots.
• Fork PRs: on public repos, GitHub withholds secrets from fork PR runs, so reviews only run for same-repo branches.

What you should do

• Use secrets only: never paste a key into YAML. Reference ${{ secrets.ANTHROPIC_API_KEY }}.
• Least permissions: give review jobs read-only permissions, as in the review example.
• Review before merge: treat Claude’s PRs like any contributor’s.
• Watch for prompt injection: issue text is untrusted input. Keep --allowedTools narrow in automation mode.
• Consider a custom app: the official app asks for a broad permission set because it also powers Code Review. A custom app can hold just Contents, Issues and Pull requests.

Warning: On public repos using a cloud provider, any comment with @claude starts the workflow, and the cloud login runs before the write-access check. Add a step that checks the commenter’s access first to avoid wasted minutes and noisy audit logs.

Troubleshooting: Common Problems and Fixes

Claude does not respond to @claude

Check that the app is installed on the repo, workflows are enabled and the secret exists. The comment must contain @claude as a whole word, and the commenter needs write access.

CI does not run on Claude’s commits

GitHub does not trigger workflows on commits made with the default GITHUB_TOKEN. Remove that github_token line so the action uses the Claude app, or pass a custom app token.

Authentication errors

Test the key or token locally with claude first. For cloud providers, check id-token: write, the repo condition in your trust policy, and the secret names.

/install-github-app exits right away

The remote is probably GitLab or Bitbucket, or gh is missing or logged out. Fix the remote or run gh auth login, then try again.

The review workflow posts nothing

Make sure the prompt has --comment and claude_args names the inline comment tool. Without them, findings only appear in the run log.

Frequently Asked Questions

Is Claude Code GitHub Actions free?

The action itself is free and open source. You pay for GitHub Actions minutes on private repos and for Claude usage through an API key or your Claude subscription.

Can I use my Claude Pro or Max plan instead of an API key?

Yes. Run claude setup-token to create a CLAUDE_CODE_OAUTH_TOKEN and pass it with the claude_code_oauth_token input. It works on Pro, Max, Team and Enterprise plans.

What version of the action should I use?

Use anthropics/claude-code-action@v1. If you still have @beta, follow the migration steps in the inputs section above.

Can I change the @claude trigger word?

Yes. Set the trigger_phrase input to any phrase you like. The default is @claude.

Which model does the action use?

It uses the Claude Code default model unless you pass --model in claude_args, for example claude-sonnet-5 or claude-opus-5-5.

Does it work with GitLab?

No, this action is GitHub only. Anthropic has a separate Claude Code GitLab CI/CD integration for GitLab pipelines.

Can people outside my team trigger Claude on a public repo?

Not by default. Users without write access are rejected unless you list them in allowed_non_write_users, but the workflow may still start before that check runs.

Sources

• Claude Code docs: GitHub Actions
• Claude Code docs: GitHub Actions with cloud providers
• anthropics/claude-code-action on GitHub
• claude-code-action releases
• Claude API pricing
• GitHub Docs: About billing for GitHub Actions