Last updated: November 20, 2026
TL;DR
Claude Code GitHub Actions is Anthropic's anthropics/claude-code-action: a GitHub Action that runs Claude Code inside your repository's workflows. Someone mentions @claude in an issue or pull request, or a workflow hands it a prompt, and Claude reads the code, answers, and can push commits (Anthropic's GitHub Actions docs). Setting it up takes four decisions:
- ๐ง How to install it:
/install-github-appfrom Claude Code, or the app, a secret and a workflow file by hand. - ๐ How it signs in: a Claude API key, a subscription token, or, for an organization, workload identity federation with no stored secret.
- ๐ฌ What starts a run: an
@claudemention, or apromptthat runs on any GitHub event, a schedule included. - ๐งฑ What a run may touch: the workflow's own permissions, who may trigger it, which tools it may use, and how long it may go.
Before you start
- Admin access to the repository. Both setup paths need it.
- A repository on github.com.
/install-github-appexits with a notice on a gitlab.com or bitbucket.org remote. GitLab has its own CI/CD integration. - The GitHub CLI, signed in with
gh auth login, for the quick setup. That is how Claude Code reaches your repository to save the secret and push the workflow files. - A credential. A Claude API key from the Claude Console, or a long-lived subscription token from
claude setup-token, available on Pro, Max, Ultra, Team and Enterprise plans.
If the job is one prompt that should run from your own script or server rather than from GitHub, that is headless mode. Our Claude Code automation guide compares every way to run it without you.
Step 1: Install with /install-github-app
Run claude in the repository, then /install-github-app at the prompt. The command walks you through the rest:
- Install the Claude GitHub App in the browser page it opens, with access to your repository, then press Enter back in Claude Code.
- Choose the workflows. Select "Set up GitHub Actions workflows", then keep or deselect the
@claudementions workflow and the pull request review workflow. - Choose the credential. A subscription token or an API key. Claude Code saves it as a repository secret,
CLAUDE_CODE_OAUTH_TOKENorANTHROPIC_API_KEY. - Confirm, then merge. Claude Code pushes a branch with the workflow files and opens a pull request for you to create. The workflows switch on when you merge it.
To test it, tag @claude in an issue comment. Press Esc to stop setup partway: Claude Code finishes the change it is writing and lists what already happened, such as a pushed branch or a saved secret.
If the repository already has a claude.yml, setup offers to update it instead. Pick "Skip workflow update (configure secrets only)" to keep yours.
Step 2: Or set it up by hand
Use the manual path when you don't run Claude Code locally, when the command fails, or when you want to own every line of the workflow:
- Install the Claude GitHub App on the repository.
- Add one secret:
ANTHROPIC_API_KEY, orCLAUDE_CODE_OAUTH_TOKENfromclaude setup-token. - Add a workflow under
.github/workflows/. This is the mentions workflow from Anthropic's docs:
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 }}
With a subscription token, replace the last line with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}. The if line keeps a runner from starting on comments that don't mention @claude, id-token: write is needed for the action's default GitHub App sign-in, and actions: read lets Claude read CI results on a pull request.
For an organization, install the app once at the organization level, store the secret as an organization Actions secret, and add the workflow to each repository or call one reusable workflow. Use an API key for a shared secret, since a subscription token is tied to the person who ran claude setup-token. To store no long-lived secret at all, the action can trade the workflow's GitHub OIDC token for Claude API access through a Claude Console service account (workload identity federation).
Step 3: Pick what starts a run
The action decides its mode from your workflow:
| Mode | When | Where results go |
|---|---|---|
| Interactive | No prompt input. Claude waits for @claude in a comment, a review, or a new issue's title or body | A comment on the issue or pull request, updated as it works |
| Automation | A prompt input, plain text or a skill such as /skill-name | The workflow run log, unless the prompt tells Claude to post and it has a tool that can |
In interactive mode, requests read like this:
@claude fix the TypeError in the user dashboard component
Automation mode runs on any GitHub event, a cron schedule included. This is Anthropic's daily report example: it runs at 09:00 UTC, reads commits and issues through two GitHub MCP tools, and needs no checkout step. Its last input, claude_args, passes the allowedTools flag (two hyphens before it, as on the command line) with "mcp__github__list_commits,mcp__github__list_issues". This blog names long flags without their hyphens, so that line is left out of the block below; add it, or the run has no tools to read with:
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"
GitHub runs scheduled workflows only from the default branch, and in a public repository it turns the schedule off after 60 days without activity.
Step 4: Decide what a run can touch
Four layers decide it. Set each one on purpose.
The app's permissions are wider than the action needs. The Claude GitHub App is shared by every Claude feature on GitHub, Code Review and web auto-fix included, and GitHub makes you accept its whole permission set. The action itself relies on three: Contents, Issues and Pull requests, each read and write. The rest of the set includes write access to Actions, Workflows and Repository hooks. If your organization accepts only what the action uses, create a custom GitHub App with those three permissions. It covers the action only; Code Review and web auto-fix still need the official app.
The workflow's permissions block narrows each run. The mentions workflow asks for write on contents, pull requests and issues because Claude pushes and comments. The daily report asks only for read. Give each workflow the least it needs.
Who can trigger a run is checked twice. On issue and pull request events, the person who triggered it must have write access to the repository; allowed_non_write_users, with your own github_token, opens it to named others. On every event, a bot is refused unless you list it in allowed_bots, which keeps bots from setting Claude off in a loop. Scheduled runs count as the user who last changed the cron line, so list that user if it is a bot.
Tools, turns and time. With a plain-text prompt, Claude has no shell or GitHub API access until you grant it, through allowedTools in claude_args or a permission rule in the settings input. A skill gets the tools its own allowed-tools frontmatter grants. Then cap the run: max-turns in claude_args, a timeout on the workflow, and GitHub's concurrency controls so runs don't stack.
claude_args takes any Claude Code CLI flag, written as you would on the command line, with two hyphens before each long flag. The common ones are max-turns, model, mcp-config, allowedTools and debug.
Never commit a key or token: keep it in GitHub Secrets and reference it, as the examples do. And review what Claude changes before you merge it.
Step 5: Know what each run costs
Each run spends two things:
- GitHub Actions minutes, because the action runs on GitHub-hosted runners.
- Claude usage: API tokens with an API key, or your subscription with a subscription token.
Anthropic's ways to spend less: write specific @claude requests so Claude needs fewer turns, use issue templates to give context up front, keep CLAUDE.md short since Claude reads it on every run, and cap turns, time and parallel runs as in Step 4.
To route the calls through your own cloud account instead, set use_bedrock, use_vertex or use_foundry to "true". All three sign in through OIDC, so no static cloud credentials sit in the repository. Our Claude Code on Bedrock guide covers when a team should route through AWS.
Upgrading from the beta
If a workflow still uses anthropics/claude-code-action@beta: change @beta to @v1, remove the mode input (v1 detects it), rename direct_prompt to prompt, and move options such as max_turns and model into claude_args. custom_instructions becomes the append-system-prompt flag.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Claude doesn't answer @claude | App not installed, workflows disabled, or secret missing | Check all three in the repository settings |
| Claude doesn't answer one person | They lack write access | Grant it, or list them in allowed_non_write_users with your own github_token |
@claude-bot or /claude does nothing | The trigger must be @claude as a whole word | Use @claude, or set trigger_phrase |
| CI doesn't run on Claude's commits | Commits made with the default GITHUB_TOKEN don't trigger workflows | Remove the github_token input so the action signs in as the Claude app, or pass a custom app token |
| A scheduled run fails the actor check | The user who last changed the cron line is a bot | Add it to allowed_bots |
| Authentication errors | The key or token is invalid | Test it locally with claude before debugging the workflow |
Frequently asked questions
What is Claude Code GitHub Actions?
It's Anthropic's GitHub Action, anthropics/claude-code-action, that runs Claude Code inside your repository's workflows. Claude answers @claude mentions in issues and pull requests, and can run a prompt on any GitHub event, a schedule included, to analyze code, make changes and push commits. It's built on the Claude Agent SDK.
How do I set up Claude Code in GitHub Actions?
Run /install-github-app in Claude Code inside the repository. It installs the Claude GitHub App, saves your API key or subscription token as a repository secret, and opens a pull request with the workflow files; merge it to switch them on. Or install the app, add the secret and copy a workflow file yourself.
Can I use my Claude subscription with Claude Code GitHub Actions?
Yes. Run claude setup-token locally to get a long-lived OAuth token, available on Pro, Max, Ultra, Team and Enterprise plans, save it as CLAUDE_CODE_OAUTH_TOKEN, and pass it to the claude_code_oauth_token input. For a secret shared across an organization, use an API key, since the token is tied to one person's subscription.
Who can trigger Claude in GitHub Actions?
On issue and pull request events, only users with write access to the repository, unless you list others in allowed_non_write_users and pass your own github_token. Bots are refused on every event unless listed in allowed_bots, which stops trigger loops. Scheduled runs skip the write-access check but not the bot check.
What permissions does the Claude GitHub App need?
The action uses three: Contents, Issues and Pull requests, each read and write. The official app asks for a wider set because Code Review and other Claude features share it, and GitHub doesn't let you accept part of it. An organization that wants only the three can create a custom GitHub App for the action.
How much does Claude Code GitHub Actions cost?
Each run uses GitHub Actions minutes on GitHub-hosted runners, plus Claude usage: API tokens with an API key, or your subscription with an OAuth token. Keep both down with specific requests, a short CLAUDE.md, the max-turns flag in claude_args, workflow timeouts and concurrency limits.
Can Claude Code GitHub Actions run on a schedule?
Yes. Give the action a prompt input and trigger the workflow with a cron schedule. Grant the tools the prompt needs with allowedTools in claude_args or a permission rule, since a plain-text prompt starts with no shell or GitHub API access. GitHub runs schedules only from the default branch.
Give every run the same rules
A workflow run starts fresh each time, and the one thing it reads on every run is your repository's CLAUDE.md: Anthropic's docs point there for code style, review criteria and project rules. Keeping that file short and adding a rule each time a run goes wrong is the method in our guide to compound engineering for Claude Code. For guardrails that fire on every tool call, see our hooks guide.
Stop guessing. Score your first workflow.
Score one workflow in about five minutes. Nine questions, a grade, and the specific gap holding it back - no call required.
Related Posts

Claude Code SDK or claude -p: which one to script against
The Claude Code SDK is now the Claude Agent SDK, and it runs the same agent as claude -p. When a script should call claude -p, when your code needs the SDK, what each loads by default, and how each signs in.

Claude Code PR review: four ways to review every pull request, and which to pick
Managed Code Review, Claude in your own CI, /code-review in your session, or ultrareview: what starts each Claude Code PR review, where it runs, what it costs, and which to pick for your plan and code host.

Claude Code headless mode: run claude -p from scripts, with output you can parse and a cap on spend
Claude Code headless mode runs one prompt with claude -p and exits. How to make runs repeatable with bare mode, approve tools without a prompt, read JSON output, and cap turns and spend.
