What Claude Code GitHub Actions actually is
Claude Code GitHub Actions is an official GitHub Action, published as anthropics/claude-code-action@v1, that runs Claude Code inside a GitHub Actions runner rather than on your machine. It reads the repository, can be tagged from a pull request or issue comment, and can be triggered automatically by workflow events. In practice it turns the same agent you already run in the desktop app into something that also works while you are asleep.
That is the whole idea, and it is worth being blunt about why it matters. The desktop app is where you do the thinking. CI is where you do the repetition. Anything you find yourself typing into Claude Code for the fifth time on a Tuesday afternoon is a candidate to move into a workflow file, because a workflow file never forgets and never gets bored.
The fastest install path
There are two ways in, and one of them takes about a minute. From inside Claude Code, run the /install-github-app command in a terminal session pointed at your repository. It walks the GitHub App installation and drops the workflow file in for you.
If you would rather do it by hand, or your organization restricts app installs, the manual route is three steps.
- Install the Claude GitHub App on the repository or the whole organization.
- Add your credential as a repository secret. That is either ANTHROPIC_API_KEY for API billing, or CLAUDE_CODE_OAUTH_TOKEN if you are authenticating against a subscription.
- Copy the example workflow into .github/workflows/claude.yml and commit it.
The manual route is worth knowing even if you use the command, because when something breaks later you will want to know which of those three pieces is missing. Nine times out of ten a silent no-op is a missing secret.
Interactive mode versus automation mode
This is the single concept that determines how the action behaves, and it is controlled by one input.
The two modes of anthropics/claude-code-action@v1
| Mode | How you get it | What triggers a run |
|---|---|---|
| Interactive | Omit the prompt input entirely | A human writes @claude in an issue or pull request comment |
| Automation | Supply a prompt input | Whatever workflow event you listed, with no human in the loop |
Interactive mode is the one most teams start with, because it is opt-in by definition. Nothing happens until somebody asks. Automation mode is the one that produces real leverage and real bills, because it fires on every matching event whether or not anyone wanted it to.
My rule of thumb is to launch every new workflow in interactive mode, live with it for a week, and only convert it to automation once I have seen enough of its output to trust what it does unattended.
The permissions the workflow needs
The example workflow requests a specific set of permissions, and each one exists for a reason. If you trim the block without understanding it, the action fails in ways that look like bugs.
- contents: write, so Claude can push commits and branches.
- pull-requests: write, so it can open pull requests and leave review comments.
- issues: write, so it can respond in issue threads.
- id-token: write, which the action uses for its OIDC authentication flow.
- actions: read, so it can inspect workflow runs when it needs CI context.
Passing CLI arguments with claude_args
Everything you would normally pass to the Claude Code CLI goes through the claude_args input. That includes --model to pin a specific model, --allowedTools to constrain what the agent is permitted to touch, and --max-turns to put a hard ceiling on how long it will keep working.
Of those, --allowedTools is the one people skip and later regret. An agent in CI with an unconstrained tool list has more reach than most contractors you would hire. Give it the narrowest set that lets the job finish.
Cost controls that actually work
An agent in CI has no natural stopping point. It does not get tired and it does not notice that it has been going for forty minutes. Four controls carry most of the weight.
- Set --max-turns in claude_args. This is the most direct cap on how much work a single run can do.
- Set a job-level timeout in the workflow. Belt and braces, and it catches the case where a single turn hangs.
- Add a concurrency group with cancel-in-progress. Without it, five pushes in five minutes start five agents.
- Keep CLAUDE.md concise. It is loaded into context on every run, so a bloated one is a fixed tax on every job you ever trigger.
The gotcha that wastes an afternoon
When the action commits using the default GITHUB_TOKEN, GitHub will not run your other workflows on that commit. This is standard GitHub behavior, designed to stop workflows from triggering each other in a loop, and it is not specific to Claude.
The symptom is confusing. Claude opens a pull request, the code looks fine, and your test suite simply never runs on it. Nothing errors. The checks are just absent. If you need downstream CI to fire on agent-authored commits, you need a different token than the default one.
How to roll this out without regretting it
The pattern that has worked for me is deliberately slow, and it is the same shape as onboarding a new contractor.
- Install on one repository, not the organization. Pick one you would not mind explaining to your team.
- Start interactive. Tag @claude by hand for a week and read every response properly.
- Write the CLAUDE.md before you automate anything. Most bad CI output is missing context, not a bad model.
- Convert one job to automation mode. One. Watch the bill for a few days before you add a second.
- Only then widen the tool list, and only for the specific thing that was blocked.
If you want to go deeper on the context file that all of this depends on, we covered how to keep it from bloating in [the Claude Code rules directory](/blog/claude-code-rules-directory).
Where this fits in a build workflow
The honest summary is that CI Claude is not a replacement for desktop Claude. It is a second surface with different economics. Desktop is interactive, cheap to correct and expensive in your attention. CI is unattended, cheap in attention and expensive if you do not cap it.
Use the desktop app for the work that needs judgment, and push the repetitive checks into Actions once you have watched them enough to know what they produce. That split is the whole game.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
What is the Claude Code GitHub Action called?
It is published as anthropics/claude-code-action@v1. You reference it in the uses field of a step in your workflow file, the same way you would reference any other action.
How do I install Claude Code GitHub Actions?
The quickest path is the /install-github-app command from inside Claude Code, which sets up the GitHub App and the workflow file for you. Manually, you install the Claude GitHub App, add ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a repository secret, and copy the example workflow into .github/workflows.
What is the difference between interactive and automation mode?
It comes down to whether you supply the prompt input. Without it, the action is interactive and only responds when someone writes @claude in an issue or pull request comment. With it, the action runs automatically on the workflow events you configured, with no human trigger.
How do I stop a Claude Code workflow from getting expensive?
Cap turns with --max-turns in claude_args, set a job timeout in the workflow, add a concurrency group so simultaneous pushes do not spawn parallel agents, and keep CLAUDE.md short because it is loaded on every single run.
Why did my tests not run on the commit Claude pushed?
GitHub does not trigger workflows on commits made with the default GITHUB_TOKEN. This is a platform-level loop-prevention rule rather than anything specific to Claude. If you need downstream CI on agent-authored commits, authenticate the commit with a different token.
Last reviewed by David Iya on August 13, 2026
