What Is the Claude Code GitHub Action?
The Claude Code GitHub Action is Anthropic's official workflow component that runs Claude Code inside a GitHub-hosted runner. It lets Claude review pull requests, respond to issue comments, write tests, refactor code, and open branches on your behalf -- all triggered from GitHub events.
Under the hood, the action installs Claude Code inside the runner, pipes the triggering event into a prompt, and runs Claude in headless mode with tool access scoped to the repo.
anthropics/claude-code-action
Maintained by Anthropic. Pinned to semver tags like @v1. Works with the Anthropic API, Amazon Bedrock, and Google Vertex AI.
Claude Code GitHub App
One-click install from Claude Code with /install-github-app. Writes the workflow file and creates the secret for you.
The 3-Minute Install
The fastest path to a working Claude-in-GitHub setup is the official App. It installs the workflow file, creates the secret, and scopes permissions automatically.
Open Claude Code in the target repo
Navigate to the repo root and launch Claude Code. Then run:
/install-github-appAuthorize the App and pick repos
GitHub opens a consent screen. Choose specific repositories (preferred) or all repos in the org. The App requests contents, pull-requests, and issues write access.
Commit the generated workflow
The App opens a pull request that adds .github/workflows/claude.yml and stores your ANTHROPIC_API_KEY as a secret. Review and merge.
Tag @claude in any PR or issue
Post a comment like @claude review this diff for race conditions. Claude responds in-thread within 30-90 seconds.
Manual Workflow: The Minimum Viable claude.yml
If you prefer to skip the App and wire it up yourself, here is the minimum viable workflow. It triggers on @claude mentions in issues, PR comments, and review comments.
name: Claude Code
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
pull_request_review:
types: [submitted]
issues:
types: [opened, assigned]
jobs:
claude:
if: contains(github.event.comment.body, '@claude') || contains(github.event.review.body, '@claude') || contains(github.event.issue.body, '@claude')
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
issues: write
id-token: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}That file does three things: listens to the right GitHub events, filters for the @claude mention string, and runs the official action with your API key.
Why fetch-depth: 0 matters
The default shallow checkout only pulls the latest commit. Claude often needs git history for blame, diff context, and branch operations. Setting fetch-depth: 0 gives it the full history at a minor storage cost.
The complete playbook
Get every workflow file, every secret rotation pattern, and the full cost model in the KaiShips Guide to Claude Code.
This post covers GitHub Actions. The guide covers hooks, skills, MCP servers, memory architecture, cron automation, and 6 more chapters of production-tested configs.
Get the KaiShips Guide to Claude Code -- $29Trigger Patterns That Actually Get Used
@claude mentions are the default, but they are not the only option. Here are the five trigger patterns teams actually ship.
1. Mention trigger (default)
Fires on any comment containing @claude. Easiest to control, easiest for humans to opt in. Works for 80% of use cases.
2. Label trigger
Fires when a PR or issue gets a specific label like claude-review. Good for team workflows where maintainers gate the bot explicitly.
on:
pull_request:
types: [labeled]
jobs:
claude:
if: github.event.label.name == 'claude-review'3. Scheduled trigger
Runs Claude on a cron schedule. Good for nightly security sweeps, dependency audits, or stale-issue triage.
on:
schedule:
- cron: '0 6 * * *' # 6 AM UTC daily4. Workflow_dispatch trigger
Lets you run Claude manually from the Actions tab with custom inputs. Useful for one-off refactors, audits, or doc generation runs.
5. Push trigger
Fires on every push to a branch. Use sparingly -- every push costs API tokens. Best gated to a specific branch like main or paired with path filters.
7 Production Workflows Worth Stealing
These are workflow patterns running in real repositories today. Each one is cheap to run, safe to start with, and compounds value the more you use it.
Automatic PR review on open
Fires on pull_request: [opened, synchronize] and posts a review comment with code quality notes, security concerns, and missed test coverage.
@claude fix this issue -> PR
When a maintainer tags @claude on an issue with a reproduction, Claude branches, writes the fix, adds a test, and opens a PR. Human reviews and merges.
New-issue triage bot
On issues: [opened], Claude asks for missing info, applies labels, and tags the right team. Cuts maintainer triage time by 50-70%.
Doc-drift check on merge
After a merge to main, Claude reads the diff and opens a follow-up PR updating README, CHANGELOG, and /docs when they drift from the implementation.
Missing-test generator
Tag @claude add tests on any PR and Claude scans the diff, writes unit tests, and commits them back to the branch.
Nightly security sweep
Scheduled cron at 6 AM UTC. Claude scans the repo for hardcoded secrets, outdated deps with known CVEs, and risky patterns. Opens an issue if anything surfaces.
Automated release notes
On tag push, Claude generates release notes from the commit range, groups changes by type, and updates the GitHub release.
Permissions and Security
Claude runs inside your repo with a GITHUB_TOKEN. Scope that token tightly. The action inherits whatever permissions your workflow declares -- less is safer.
Minimum Permissions by Use Case
| Use case | contents | pull-requests | issues |
|---|---|---|---|
| PR review only | read | write | none |
| Issue triage | read | none | write |
| Code fixes / PRs | write | write | write |
| Release notes | write | none | none |
Security Checklist
- ●Pin the action to a SHA. Use
anthropics/claude-code-action@abc1234in production, not@v1. - ●Store API key in org secrets. Never inline the key in workflow files.
- ●Gate fork PRs. Use
pull_request_targetwith strict permissions or skip untrusted fork PRs entirely. - ●Require reviews on Claude PRs. Treat Claude-authored commits as any other contributor -- branch protection and code review rules still apply.
- ●Audit the token scope. Set
permissions:at the job level, not the workflow level, when possible.
Custom Instructions via CLAUDE.md
Claude Code reads CLAUDE.md from the repo root at runtime. The same file that guides your local Claude Code sessions also configures the Action. Keep it checked in and Claude will follow project conventions, run the right test commands, and avoid files you mark off-limits.
What to put in CLAUDE.md for CI
- ●Test command.
npm test,pytest, etc. - ●Build command. The command Claude should run to verify code compiles.
- ●Coding conventions. Formatter, linter, naming style, import order.
- ●Red lines. Files and directories Claude should never touch (generated files, vendored deps, migration files).
- ●Commit style. Conventional Commits, sign-offs, no emoji, etc.
Cost: What You Actually Pay
Running Claude in GitHub Actions has two cost centers: GitHub Actions minutes and Claude API tokens. The API tokens dominate in practice.
| Workflow type | Tokens (typical) | Cost (Sonnet 4.6) | Runner time |
|---|---|---|---|
| Small PR review | ~15K in / 2K out | $0.08 | ~1 min |
| Medium PR review | ~60K in / 5K out | $0.26 | ~2 min |
| Issue triage | ~8K in / 1K out | $0.04 | ~1 min |
| Fix + test PR | ~100K in / 15K out | $0.53 | ~3-5 min |
| Nightly security sweep | ~80K in / 3K out | $0.29 | ~3 min |
GitHub Actions minutes are free for public repos. Private repos get 2,000 minutes/month on Free, 3,000 on Pro, and 50,000 on Enterprise before overage charges of $0.008/minute on Linux.
Cost Controls
- ●Use Sonnet, not Opus. Set
model: claude-sonnet-4-6in the action inputs. 5x cheaper at comparable review quality. - ●Filter events aggressively. Gate on labels, mentions, or specific file paths. Every event is an opportunity to spend tokens.
- ●Cap runtime. Set
timeout-minutes: 10on the job so a stuck run cannot burn hours of compute. - ●Set a monthly API budget. Anthropic Console lets you cap spending per org. Set it at 2-3x your expected monthly cost.
The complete playbook
Get every workflow file, every secret rotation pattern, and the full cost model in the KaiShips Guide to Claude Code.
This post covers GitHub Actions. The guide covers hooks, skills, MCP servers, memory architecture, cron automation, and 6 more chapters of production-tested configs.
Get the KaiShips Guide to Claude Code -- $29Bedrock and Vertex: Enterprise Auth
If your organization requires Claude calls to go through AWS Bedrock or Google Vertex AI, the action supports both. Swap the API key input for cloud credentials via OIDC.
Use OIDC with aws-actions/configure-aws-credentials, then set use_bedrock: true. The action picks up the AWS session automatically.
Use google-github-actions/auth with Workload Identity Federation, then set use_vertex: true. Claude calls route through your GCP project.
Troubleshooting Common Failures
Claude never responds to @claude
Check the Actions tab. The job may be skipping because the event type is not in the on: list, or the conditional filter is not matching. Review comments fire on pull_request_review_comment, not issue_comment.
Permission denied when pushing a branch
The workflow is missing contents: write. Also check that branch protection does not require a separate status check or signed commits Claude cannot provide.
API key not found
Secrets do not pass to workflows triggered from forks by default. Either use pull_request_target (with extra caution) or limit Claude to non-fork events.
Claude runs out of context on large PRs
Add a path filter so Claude only reviews the changed files, not the whole repo. You can also bump to Sonnet 4.6 which has a larger context window than older models.
Runs succeed but nothing shows up on the PR
Claude may have posted to the wrong event context. Check logs for the "posting comment to" line. If you trigger on issue_comment on a PR, the PR number lives in github.event.issue.number.
How It Compares to Other AI-in-CI Tools
Claude Code in Actions is one option in a growing category. Here is how it stacks up.
| Tool | Model control | Code write | Self-host |
|---|---|---|---|
| Claude Code Action | Full | Yes (branches, PRs) | Yes |
| GitHub Copilot Workspace | None | Yes | No |
| CodeRabbit | Limited | Review only | No |
| Greptile | Limited | Review only | No |
| Roll-your-own (SDK) | Full | Whatever you build | Yes |
The Claude Code Action sits between review-only bots and SDK-level custom work. You get code authorship and full model choice without building the plumbing yourself.
Frequently Asked Questions
What is the Claude Code GitHub Action?
The Claude Code GitHub Action is the official anthropics/claude-code-action workflow published by Anthropic. It runs Claude Code inside a GitHub-hosted runner and lets you trigger Claude on pull requests, issues, and comments. Typical triggers include @claude mentions, specific labels, or scheduled cron events. It supports the Anthropic API, Amazon Bedrock, and Google Vertex AI.
How much does Claude Code on GitHub Actions cost?
You pay two things: GitHub Actions minutes and Claude API tokens. GitHub Actions is free for public repositories and includes 2,000-50,000 minutes per month for private repositories depending on plan. Claude API tokens at Sonnet 4.6 pricing are $3/MTok input and $15/MTok output. A typical PR review run costs $0.02-$0.20 in API tokens plus about 1-3 Actions minutes.
Do I need the GitHub App or the GitHub Action?
The GitHub App is the easiest path -- install it once from claude.ai/code/install-github-app and it sets up the Action and secrets automatically. The raw GitHub Action (anthropics/claude-code-action) gives you more control: custom runners, self-hosted infrastructure, and fine-grained permissions. Most teams should start with the App and migrate to the raw Action only if they hit a limit.
Can Claude Code write code in GitHub Actions?
Yes. When Claude Code runs inside a GitHub Action, it can read the repo, create a branch, commit changes, and push a pull request. You control this with permissions in the workflow file: contents:write for commits, pull-requests:write for PRs, and issues:write for issue comments. The default Anthropic workflow includes these permissions scoped to the triggering event.
How do I trigger Claude Code from a pull request?
Tag @claude in any PR comment, issue comment, or review comment. The default workflow fires on issue_comment, pull_request_review_comment, and pull_request_review events, filters for the @claude mention, then launches Claude Code in a runner. You can also trigger on labels, schedules, or workflow_dispatch for manual runs.
Is Claude Code GitHub Actions safe for private repos?
Yes, if configured correctly. Store your Anthropic API key in repository or organization secrets, never inline. Scope the GITHUB_TOKEN with the minimum required permissions (contents, pull-requests, issues as needed). Pin the action to a commit SHA in production workflows to prevent supply-chain surprises. Review all Claude-authored commits before merging, same as any contributor.
Can I self-host the runner for Claude Code?
Yes. Replace runs-on: ubuntu-latest with runs-on: self-hosted or your custom runner label. This is useful for accessing private network resources, avoiding GitHub-hosted runner costs for heavy workloads, or meeting compliance requirements. The action itself is a standard GitHub Action and runs anywhere the GitHub Actions runner runs.
Bottom Line
The Claude Code GitHub Action is the cheapest path to a production AI coworker. Install the App, tag @claude, and a capable coding agent shows up inside your PRs at $0.08-$0.50 per run.
Start narrow. Pick one workflow -- PR review on open, issue triage, or nightly security sweep -- and let it run for a week. Review every output before merging. Expand scope only after Claude has earned your trust on the boring stuff.
The hard part of AI-in-CI is not wiring up the workflow. It is deciding what you actually want Claude to own, and what humans still need to touch. The action gets you to that question in 3 minutes.
The complete playbook
Get every workflow file, every secret rotation pattern, and the full cost model in the KaiShips Guide to Claude Code.
This post covers GitHub Actions. The guide covers hooks, skills, MCP servers, memory architecture, cron automation, and 6 more chapters of production-tested configs.
Get the KaiShips Guide to Claude Code -- $29