CONCEPT @claude in a PR or issue triggers the action
Claude Code GitHub Actions brings the same headless Claude Code (8.1) into your GitHub workflow. Once set up,
a plain @claude mention in any pull-request or issue comment lets Claude analyze
code, implement features, fix bugs, and open PRs — all on GitHub's runners, following your CLAUDE.md.
The engine is the anthropics/claude-code-action GitHub Action, which is itself
built on top of the Claude Agent SDK (8.5).
/install-github-app in the Claude Code terminal. It installs
the Claude GitHub App on your repo, then walks you through adding the workflow files and the
ANTHROPIC_API_KEY secret. (You must be a repo admin.)Manual setup is three steps: install the app at github.com/apps/claude, add
ANTHROPIC_API_KEY to repository secrets, and copy the example workflow into
.github/workflows/. The app needs read & write on Contents, Issues, and Pull requests.
CONCEPT Two modes, one v1 action
The v1 action auto-detects how to run based on your config — you no longer set a mode:
| Mode | When | Behavior |
|---|---|---|
| Interactive | Triggered by a comment, no prompt set | Responds to @claude mentions in the thread |
| Automation | A prompt input is supplied | Runs immediately — e.g. scheduled reports, auto-review on every PR |
Key v1 inputs on anthropics/claude-code-action@v1:
| Input | Purpose |
|---|---|
anthropic_api_key | Your Claude API key — always from ${{ secrets.ANTHROPIC_API_KEY }}, never hardcoded. |
prompt | Instructions (plain text or a skill name). Omit for pure @claude-reply mode. |
claude_args | Any Claude Code CLI flags passed through, e.g. --max-turns 10, --model, --allowedTools, --mcp-config. |
trigger_phrase | Custom trigger (default @claude). |
use_bedrock / use_vertex | Use Amazon Bedrock / Google Cloud instead of the Claude API (enterprise, OIDC auth). |
@beta → @v1, delete
mode: (now auto-detected), rename direct_prompt → prompt, and move
max_turns / model / allowed_tools into claude_args.DIAGRAM The @claude round-trip
in a PR or issue"] --> GH["GitHub event fires
(issue_comment, PR review comment)"] GH --> WF[".github/workflows/*.yml
if: contains(body, '@claude')"] WF --> ACT["anthropics/claude-code-action@v1
uses ANTHROPIC_API_KEY secret"] ACT --> RUN["🟢 Claude runs on GitHub runner
reads CLAUDE.md, edits code"] RUN --> OUT["🔵 Comments back / pushes a branch / opens PR"] OUT --> REV["👤 You review & merge"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef info fill:#cfe2ff,stroke:#0d6efd,color:#084298; class RUN ok; class OUT info;
CODE A minimal workflow & an automation workflow
Left: reply to @claude mentions. Right pattern: run a prompt on a schedule. Both use the v1
action and a secret-held key.
# .github/workflows/claude.yml — responds to @claude in comments name: Claude Code on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: claude: runs-on: ubuntu-latest steps: - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # no prompt → interactive: replies to @claude mentions
# Automation: scheduled daily report — a prompt makes it run immediately on: schedule: - cron: "0 9 * * *" jobs: report: runs-on: ubuntu-latest 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 opus --max-turns 10"
TRADE-OFFS GitHub Action vs. rolling your own claude -p in CI
✅ claude-code-action@v1
- Turnkey:
@claudementions, auto mode detection - GitHub App handles PR/issue permissions & commits
- Bedrock/Vertex support via OIDC for enterprise
claude_argsexposes the full CLI when needed
⚙️ Raw claude -p in a CI step
- Works on any CI (GitLab, Jenkins, etc.)
- Full control over the shell pipeline
- But: you wire up triggers, comments, and auth yourself
- No built-in
@claudemention handling
--max-turns in claude_args, workflow timeouts,
and concurrency limits.EXAM TRAPS
/claude." → The default trigger is
@claude (a mention), not a slash command. If it's not responding, confirm the comment says
@claude and the App is installed.mode: tag and max_turns directly." → v1
auto-detects the mode (drop mode:) and CLI options like max_turns move into
claude_args (e.g. --max-turns 10). direct_prompt became
prompt.ANTHROPIC_API_KEY repository secret and reference
${{ secrets.ANTHROPIC_API_KEY }}.claude -p, wrapped for GitHub
events.PRACTICE
Q1 · What's the quickest way to set up the GitHub integration, and what does it do?
Run /install-github-app in the Claude Code terminal (as a repo admin). It installs
the Claude GitHub App on the repo, then walks you through adding the workflow files and the
ANTHROPIC_API_KEY secret.
Q2 · A beta workflow sets mode: "tag" and max_turns: "10". Convert it to v1.
Use anthropics/claude-code-action@v1, delete the mode line (auto-detected),
and move the turn cap into claude_args: "--max-turns 10". Also rename any
direct_prompt to prompt.
Q3 · You want Claude to run on a cron schedule with no human mention. What must the workflow include?
Supply a prompt input (which puts the action in automation mode so it runs
immediately) under an on: schedule cron trigger, plus the anthropic_api_key secret.
Add claude_args like --max-turns to bound cost.