Claude Code GitHub Actions: setup and workflows

Claude Code GitHub Actions lets you run Claude Code inside a GitHub workflow. You mention @claude in an issue or pull request, and Claude reads the code, answers, writes a fix on a new branch or reviews the diff, all on a GitHub runner. The fastest setup is to open Claude Code in your repository and run /install-github-app. It installs the Claude GitHub App, stores your key as a repository secret and opens a pull request with the workflow files.

This guide covers both setup paths, the inputs of the official anthropics/claude-code-action, the two modes (mentions and automation), a ready-made PR review workflow, secrets, cost and permission controls, and the cases where running Claude locally is the better choice. Everything here follows Anthropic’s documentation and the action’s README as of October 2026. If what you want is an agent that fixes red CI builds by itself, that has its own post: auto-fix CI failures with AI.

What the action does

anthropics/claude-code-action@v1 is a GitHub Action that runs the Claude Code agent on your own GitHub runner. It works in two modes:

• Interactive (mentions). If you don’t give it a prompt, it waits for a trigger phrase, @claude by default. The phrase can be in an issue or PR comment, a PR review, or the title or body of a new issue. Claude replies in a comment and can push a branch with changes.
• Automation. If you set prompt, Claude runs that task as soon as the workflow fires, with no mention needed. Results go to the run log unless the prompt or a plugin tells Claude to post somewhere. This is how you build PR reviews, scheduled reports and issue triage.

The agent follows the same rules as in your terminal. It reads CLAUDE.md, uses the tools you allow and stops at the turn limit you set.

Step 1: quick setup with /install-github-app

Open Claude Code in the repository and run:

/install-github-app

Before you start, check three things:

• You are a repository admin. Installing the app and adding secrets both need admin rights.
• The repository is on github.com. If the remote is on gitlab.com or bitbucket.org, the command shows a notice and exits.
• The GitHub CLI is signed in. Run gh auth login first if you haven’t.

The command walks you through it. It installs the Claude GitHub App on the repo and asks how Claude should authenticate. It then saves either ANTHROPIC_API_KEY (an API key) or CLAUDE_CODE_OAUTH_TOKEN (a token tied to your Claude subscription) as a repository secret. If a key already exists it can reuse it. Finally it pushes a branch with the workflow files and opens a pull request for you to merge.

You get two workflows: claude.yml answers @claude mentions, and claude-code-review.yml reviews pull requests. Press Esc to stop partway through, or choose “Skip for now” after the app is installed if you want to write the workflows yourself. If you run the command again later, it offers to update the workflow file to the latest version.

Quick setup works with the Claude API and with Claude subscriptions. If you use Amazon Bedrock, Google Cloud or Microsoft Foundry, follow the manual path and the cloud provider section of the docs.

Step 2: manual setup

If the command doesn’t fit your situation, the same three steps by hand are:

1. Install the Claude GitHub App from github.com/apps/claude on the repository. The action uses its Contents, Issues and Pull requests permissions, each with read and write access.
2. Add a secret under Settings → Secrets and variables → Actions:
   • ANTHROPIC_API_KEY: an API key from the Claude Console, billed per token, or
   • CLAUDE_CODE_OAUTH_TOKEN: run claude setup-token locally to create one; it works with Pro, Max, Team and Enterprise plans.
3. Copy the example workflow claude.yml from the action’s examples/ folder into .github/workflows/.

Here is a working mention workflow:

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

Two permissions are easy to miss. id-token: write is required for the default GitHub App authentication. actions: read lets Claude read CI results, so you can ask it why a check failed. If you use a subscription token, swap the last line for claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

For an organization, the docs suggest installing the app at organization level, putting the key in an organization Actions secret and calling a reusable workflow from each repo. They also recommend an API key over an OAuth token for shared secrets, because a token belongs to one person’s subscription. If you’d rather not store a long-lived key at all, the action supports workload identity federation (OIDC) through the anthropic_federation_rule_id and anthropic_organization_id inputs.

Step 3: use @claude in issues and pull requests

Once the workflow is on the default branch, write a comment:

@claude why does the checkout test fail on Node 22? Fix it if the cause is in our code.

@claude implement this issue. Keep the public API unchanged and add tests.

@claude review the error handling in src/payments/ and suggest changes inline.

Claude answers in a comment. When it changes code, it pushes to a branch that starts with claude/ (the branch_prefix input changes this) and gives you a link to open the pull request. A few rules decide who can start a run:

• The person commenting needs write access. Users without it are ignored unless you list them in allowed_non_write_users, which also needs your own github_token.
• Bots are ignored unless you name them in allowed_bots. Setting it to "*" accepts every bot, which the README warns against on public repositories.
• The trigger is a whole word. @claude works, /claude and @claude-bot don’t. Change it with trigger_phrase if you need to.

There are also assignee_trigger (start when an issue is assigned to a given user) and label_trigger (start when a label is added, claude by default). Pair them with the right issues event types in on:.

Step 4: an automatic PR review workflow

The review workflow below is the one the docs ship. It runs on every opened, updated, reopened or ready-for-review pull request, without anyone typing @claude:

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

What each part does:

• plugin_marketplaces and plugins load the official code-review plugin.
• prompt runs its command on the current PR. --comment posts the findings as inline comments, or as a single summary comment.
• The claude_args line is required. Without --allowedTools for the inline comment tool, the MCP server that posts comments doesn’t start.

The plugin skips draft, closed and trivial PRs, and PRs it has already commented on. Pull requests from forks of a public repository don’t get repository secrets, so the review won’t run on them. Anthropic also offers a separate managed product called Code Review that reviews PRs without any workflow file. The action is the one you control and run on your own runner.

For a wider look at what AI review catches and what it misses, see AI code review.

Step 5: scheduled and custom automations

With prompt you can run any task on any GitHub event. A daily summary looks like this:

name: Daily report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Summarize yesterday's commits and open issues"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

Remember that with a plain prompt Claude has no shell and no GitHub API access until you grant tools with --allowedTools or a permissions.allow rule in the settings input. Scheduled workflows only run from the default branch, and GitHub disables them in public repositories after 60 days without activity.

The inputs you will actually use

The action has many inputs. These are the common ones:

Other useful ones from the README: base_branch and branch_prefix for where Claude pushes, use_sticky_comment to keep a single updating comment, track_progress to post tracking comments on PR and issue events, use_commit_signing to sign commits, and additional_permissions (for example actions: read). The action also returns outputs such as branch_name, session_id and structured_output for later steps.

If you used the beta, the upgrade is mechanical. Change @beta to @v1, remove mode, rename direct_prompt to prompt, move max_turns and model into claude_args, and turn custom_instructions into --append-system-prompt.

Secrets: what goes where

• Never put a key in a workflow file. Use ${{ secrets.ANTHROPIC_API_KEY }} or ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.
• Keep secrets at the narrowest level that works: a repository secret for one repo, an organization secret limited to selected repositories for many.
• Leave show_full_output off on public repos. The README warns that full output in the logs can expose secrets.
• Treat issue text as untrusted input. Anyone who can write an issue can try to steer Claude with instructions hidden in it. The write-access rule is your main defense, so don’t loosen allowed_non_write_users or allowed_bots casually. Prompt injection and AI coding agent security cover the risks in more depth.

Controlling cost and permissions

Every run costs twice: GitHub Actions minutes on the runner, and Claude tokens (or subscription usage if you use an OAuth token). The levers the docs recommend:

• Cap turns: claude_args: "--max-turns 5" stops a run from looping.
• Set a job timeout with timeout-minutes on the job.
• Use concurrency so a burst of pushes doesn’t start five reviews of the same PR:

concurrency:
  group: claude-${{ github.event.pull_request.number || github.event.issue.number }}
  cancel-in-progress: true

• Narrow the tools. Give --allowedTools only the commands the task needs, and keep job permissions read-only for review jobs, as in the workflow above.
• Keep CLAUDE.md short and specific. Claude loads it on every run, so a long one costs tokens each time. How to write CLAUDE.md has a template.
• Write specific requests. “@claude fix the null check in parseDate” is cheaper than “@claude look at this”. Issue templates help people write better ones.

Common pitfalls

• The workflow isn’t on the default branch. issue_comment workflows only run from the default branch, so merge the setup PR first.
• CI doesn’t run on Claude’s commits. GitHub doesn’t start workflows for commits made with the default GITHUB_TOKEN. Remove github_token: ${{ secrets.GITHUB_TOKEN }} so the action uses the Claude GitHub App, or pass a token from your own app.
• The review posts nothing. Check the --allowedTools "mcp__github_inline_comment__create_inline_comment" line, and check whether the PR is a draft or from a fork.
• Claude says it can’t run commands. In automation mode nothing is allowed by default. Add the tools to --allowedTools.

When to run Claude locally instead

The action is good at tasks where a fixed trigger leads to a bounded job: answer a question, implement a small issue, review a diff, write a daily summary. It’s a poor fit when:

• You want to steer as you go. A comment thread is slow when you need to correct the agent every few minutes. A local session lets you interrupt, approve and redirect.
• The task needs your environment: a running database, a local service, secrets that shouldn’t go to CI, or a GUI you need to look at.
• You are exploring. A long investigation burns runner minutes and tokens with nobody watching. Locally you see it drift and stop it.
• You want several agents at once, each in its own worktree, comparing approaches.

Many teams use both. The action handles routine reviews and small issues, and the heavier work happens locally where someone watches it.

Doing the local side with AgentVera

AgentVera is a desktop app that runs Claude Code, Codex, opencode and other coding-agent CLIs side by side, in real terminals, using your own installs and logins. It covers the local side of the split above:

• Agents in panes and worktrees. Run several Claude Code agents next to each other, each in its own git worktree, and see diffs and commits in the Git and GitHub panel.
• Automatic code review before you push: when an agent finishes a turn, a Claude model you pick reviews what it wrote and lists findings with severity and file:line. It can send them back to the agent. This is on the free plan.
• CI/CD center lists GitHub Actions, GitLab CI and Jenkins runs in one place. A failed run’s logs go to a new agent with one click.
• Automations (Pro and Team) can start an agent when CI turns red or a repo member comments on an open PR. The agent works in its own worktree, and AgentVera never pushes straight to the default branch.

Because AgentVera runs any agent CLI, the same setup works for other agents too. How to use opencode shows that side with a provider-agnostic agent. Download AgentVera to try it.

Wrapping up

To get Claude Code into GitHub Actions, run /install-github-app, merge the PR it opens, and write @claude in an issue. For automatic reviews, add the code-review plugin workflow with its --allowedTools line. Then keep it bounded with --max-turns, job timeouts, concurrency, read-only permissions where you can, and secrets that never touch the workflow file. Leave the long, exploratory and environment-heavy work to a local session where you can watch it.