OmniscioGuidesClaude Code GitHub Actions
Claude Code GitHub Actions: @claude in your repo
The Claude Code GitHub Action is Claude Code with no terminal attached: a person comments @claude fix this on an issue, and a runner in your own repository does the work and pushes a commit.
This page covers the two ways to set it up, the difference between a mention and a prompt, who is allowed to trigger a run, and the failure people hit most often after their first successful comment.
Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .
What the action is
claude-code-action is a GitHub Action that runs Claude Code inside your repository's workflows. Mention @claude in a pull request or issue comment and Claude analyzes the code, implements the change and pushes commits; give it a prompt instead and it runs automatically on any GitHub event.
Several products carry the Claude Code name, and Anthropic's page separates them on purpose. Code Review reviews pull requests automatically without a workflow file. Claude Code in the cloud runs sessions on Anthropic's infrastructure rather than your machine. The Agent SDK is the library for automation outside GitHub Actions, and the action itself is built on it.
Setup, whichever road you take, needs admin access to the repository.
GitLab has its own integration and it is a different job file rather than a setting here: Claude Code in GitLab CI/CD covers that road.
Source: "Claude Code GitHub Actions" in Anthropic's GitHub Actions page, read November 18, 2026.
The one-command setup
Open claude in the repository you want to connect and run /install-github-app. It installs the Claude GitHub App, sets up the authentication secret, and pushes a branch with the workflow files you pick.
The credential becomes a repository secret. An API key is saved as ANTHROPIC_API_KEY; a token made from your Claude subscription is saved as CLAUDE_CODE_OAUTH_TOKEN. The workflow files arrive already pointed at whichever one was used.
Three limits are worth knowing before you start. The command works only with github.com repositories — on a gitlab.com or bitbucket.org remote it prints a notice and exits. It wants the GitHub CLI installed and signed in with gh auth login, and warns you when it is missing. And pressing Esc stops it partway through: a step already running finishes, no later step starts, and the closing message lists what already changed in the repository.
If you choose the review workflow, Claude posts each review on the pull request itself — an inline comment per issue it finds, or one summary comment when it finds none — from v2.1.229 onward. Before that version the review went only to the workflow run log.
Source: "Setup" and "Quick setup" in Anthropic's GitHub Actions page, read November 18, 2026.
The manual road
Use this when you never run Claude Code locally, when the command fails, or when you want to own the workflow files. Three things get done by hand: install the app, add the secret, copy a workflow file into .github/workflows/. The secret is a repository secret, and the workflow references it the way the quick setup does: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}.
The Claude GitHub App relies on three permissions, and Anthropic names them exactly: Contents read and write so Claude can modify files, Issues read and write so it can answer issues, and Pull requests read and write so it can push and open pull requests. Installing it grants more than that for other Claude features.
Cloud accounts change the shape of the secret rather than the shape of the workflow. Setting use_bedrock, use_vertex or use_foundry routes inference through your own account and authenticates through federated identity (OIDC) rather than a stored key, so no static cloud credential lives in the repository at all.
Sources: "Manual setup" and "Use a cloud provider" in Anthropic's GitHub Actions page, read November 18, 2026.
Two modes: a mention or a prompt
The action reads its own workflow configuration to decide how to run, and the deciding input is prompt.
- Interactive mode — no
promptinput. Claude waits for the trigger phrase,@claudeby default, in an issue or pull request comment, in a pull request review, or in the body or title of a newly opened issue. Progress and results appear as comments on the thing that triggered it. - Automation mode — a
promptinput. Claude runs without waiting for a mention. Results go to the workflow run log by default, and reach the issue or pull request only when the prompt asks for that and Claude has a tool that can post.
That second detail catches people out. A prompt that says "review this pull request" can post a comment, because the review plugin brings a tool that posts. A plain prompt in a scheduled workflow has no shell and no GitHub API until you grant the tools it needs, with --allowedTools in claude_args or a permissions.allow rule in the settings input.
Sources: "Interactive and automation modes" and "Run on a schedule" in Anthropic's GitHub Actions page, read November 18, 2026.
The workflow file, line by line
This is Anthropic's own @claude example, unchanged in shape. Four of its lines do the work that the boilerplate around them does not:
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 }}id-token: writeis required for the action's default GitHub App authentication.actions: readlets Claude read CI results on the pull request it is working on.actions/checkoutgives it a local copy of the repository to work in.- The
if:line stops runners starting on comments that never mention@claude. The action checks the trigger phrase itself as well.
Once that file is merged, a comment is the whole interface. Anthropic's examples are @claude implement this feature based on the issue description and @claude fix the TypeError in the user dashboard component. Claude replies in a comment on the same issue or pull request and updates it as it works.
Authentication by subscription swaps one line: replace anthropic_api_key with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}, a token made with claude setup-token.
Source: "Respond to @claude mentions" and "Action parameters" in Anthropic's GitHub Actions page, read November 18, 2026.
Who can trigger a run
Every run passes two checks on the person or thing that triggered it, and the run fails when either one rejects it.
Write access. On issue and pull request events, the triggering user needs write access to the repository. Events no user authors, such as a schedule trigger, skip this check. To let named people without write access trigger Claude, set allowed_non_write_users and pass your own github_token.
A human actor. On every event a bot actor is rejected unless you list it in allowed_bots. That is what keeps two bots from triggering each other in a loop. It applies to scheduled runs too, because GitHub attributes a schedule to a repository user — usually whoever last edited the cron line. If that user is a bot, the schedule fails until the bot is listed.
Source: "Who can trigger runs" in Anthropic's GitHub Actions page, read November 18, 2026.
Automation mode and schedules
A prompt turns any event into a trigger, a cron schedule included. Anthropic's daily report example runs at 09:00 UTC, reads commits and issues through two GitHub MCP tools, and needs no checkout step at all:
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"Two scheduling rules are GitHub's rather than Claude's: scheduled workflows run only from the default branch, and on a public repository GitHub disables the schedule after 60 days without repository activity.
Source: "Run on a schedule" in Anthropic's GitHub Actions page, read November 18, 2026.
What a run costs
Each run spends two separate things. GitHub-hosted runners consume your GitHub Actions minutes, billed by GitHub. And each interaction consumes API tokens, billed by Anthropic — unless you authenticated with a subscription token, in which case the run draws on your Claude plan instead.
Anthropic's own list of ways to lower both is mostly about narrowing the job: write specific @claude requests so fewer turns are needed, use issue templates to put context up front, keep CLAUDE.md short because Claude reads it on every run, set --max-turns in claude_args, set workflow-level timeouts, and use GitHub's concurrency controls to limit parallel runs.
Sources: "Manage costs" and "Define project standards in CLAUDE.md" in Anthropic's GitHub Actions page, read November 18, 2026.
Common mistakes
- Passing
github_token: ${{ secrets.GITHUB_TOKEN }}. GitHub does not trigger workflows on commits made with that default token, so your checks never run on Claude's push. Remove the input, or pass a custom app token. - Typing
/claudeor@claude-bot. The trigger phrase has to be@claudeas a complete word. - Expecting a scheduled run to work on a public repo forever. GitHub disables the schedule after 60 days with no repository activity.
- Asking for a comment from a plain prompt. In automation mode the result goes to the run log unless the prompt gives Claude a tool that posts.
- Committing the key to make it available. Anthropic's warning is blunt: always store it as a GitHub Secret and reference it as
${{ secrets.ANTHROPIC_API_KEY }}. - Leaving a
@betaworkflow in place. Onclaude-code-action@v1themodeinput is gone,direct_promptbecameprompt, andmax_turnsandmodelmoved intoclaude_args.
Sources: "Troubleshooting", "Protect your credentials" and "Upgrade from beta" in Anthropic's GitHub Actions page, read November 18, 2026.
Where these answers come from
- Everything on this page: Claude Code GitHub Actions, read November 18, 2026. The setup steps, the two modes, the trigger checks, both example workflows, the cost list and the troubleshooting entries all sit on that one page.
- The CLI arguments
claude_argsaccepts are the ordinary ones, listed in the CLI reference. - Working from a terminal instead of a workflow is headless mode, which is the same print mode a CI job can call directly.
- Running a review on every pull request without a workflow file is the local review command's enterprise neighbour, Code Review.
Common questions
Does the action run on every push?
No. Without a prompt input it waits for @claude in a comment, a review, or a new issue. It runs on a push only if you add a workflow that fires on push and passes a prompt.
Why do my checks not run on the commits Claude pushes?
GitHub does not trigger workflows on commits made with the default GITHUB_TOKEN. Drop the github_token input so the action authenticates as the Claude GitHub App, or pass a custom app token.
Can anyone in the repository trigger Claude?
On issue and pull request events they need write access. Named people without it can be allowed with allowed_non_write_users plus your own github_token.
Can I use Bedrock, Vertex or Foundry?
Yes. Set use_bedrock, use_vertex or use_foundry. Authentication is OIDC identity federation, so no static cloud credential lives in the repository.