GitHub Actions 集成:让 Claude 在 CI 里跑

原文:https://code.claude.com/docs/en/github-actions 官方 Action:https://github.com/anthropics/claude-code-action(@v1 GA) GitHub App:https://github.com/apps/claude 官方定位:Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow.

🔥 影响力卡片

维度	数据
主要 repo	anthropics/claude-code-action — 撰文时 @v1 GA(从 @beta 演进)
一键安装	/install-github-app(在 CLI 里跑)— 自动装 App、加 secret、写 workflow
触发方式	@claude mention(在 issue / PR / 评论里)+ 任意 GitHub event(schedule / push / pull_request 等)
Provider 支持	直连 Claude API、Amazon Bedrock(走 IAM OIDC)、Google Vertex AI(走 Workload Identity Federation)
跟 Routines 区别	GHA 在 GitHub runner 上跑(你写 yaml,有完整 CI 环境);Routines 在 Anthropic 云 上跑(Claude 自主操作)
安全模型	API key 走 GitHub Secrets;Claude GitHub App 用 OAuth-like 权限模型

🎯 为什么必读

1. 这是 Claude 进入团队 CI 流水线的官方门票。

之前要让 AI 评 PR,要么自己写 webhook + 调 Anthropic API,要么用第三方工具(Greptile / CodeRabbit)。现在 Anthropic 自己出了 GitHub Action,一行 @claude implement this feature 就够。

2. 跟 Routines 的关系:互补不冲突。

场景	用哪个
想用 GitHub 完整 CI 环境(matrix / cache / artifacts / 已有 step)	GHA
想让 Claude 自主决定怎么做(open-ended task)	Routines
想 @claude 在 PR 评论里互动	GHA
想 GitHub event 触发(PR open / release publish)	两个都能,但 Routines 更简单
想自己控制 prompt / Skills / 模型	GHA
想让 Claude 在云上自己跑没有本地 runner	Routines

3. 给独立开发者的特别价值

如果你的 demo 项目都有 CI,加一个 claude.yml 几乎 0 成本:

• @claude review → 自动 PR 评论
• schedule: cron: '0 9 * * *' → 每天早上自动检查所有 PR
• @claude implement #42 → Claude 自己读 issue + 写代码 + 开 PR
• 测试挂时自动 @claude fix the failing test

一句话总结

GitHub Actions 集成 = 在 GitHub Actions runner 上跑 anthropics/claude-code-action@v1,通过 @claude mention 或任意事件触发,跑完它有 GitHub PR / issue 写入权限,可以开 PR / 留评论 / 改文件。

💎 金句墙

★ “Just open claude and run /install-github-app.” “打开 Claude,跑 /install-github-app 就完了。” —— 🟢 这是整个 ecosystem 里最甜的入门体验之一 — 不用读 docs,不用配 yaml,自己引导你完成

★ “The action now automatically detects whether to run in interactive mode (responds to @claude mentions) or automation mode (runs immediately with a prompt).” (v1 GA) “v1 自动判断是 interactive 模式(响应 @claude mention)还是 automation 模式(直接跑 prompt)。” —— 🟢 v1 比 beta 简单很多 — 不用再显式设 mode: "tag"

★ “Your code stays on Github’s runners.” “你的代码留在 GitHub runners 上。” —— 🟢 跟 Routines 的差别 — Routines 在 Anthropic 云跑,GHA 在 GitHub runners 跑 — 数据驻留 / 成本 / 工具可用性都不一样

📋 核心精读

1. 5 分钟接入(/install-github-app)

> claude
> /install-github-app

它会引导你:

1. 装 Claude GitHub App 到你的 repo
2. 添加 ANTHROPIC_API_KEY 到 repo secrets
3. 写一个 .github/workflows/claude.yml(从 examples 复制)
4. 测试 @claude mention

前提:你必须是 repo admin(才能装 App 和加 secret)。

2. 最小 workflow 范例

# .github/workflows/claude.yml
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 }}
          # 默认响应 @claude mentions

装好后,在任何 PR / issue 评论里 @claude implement this,Claude 就开始工作。

3. 5 个真实场景

A. @claude mention 互动

最直接的用法。任何 issue / PR 评论里:

@claude implement this feature based on the issue description
@claude how should I implement user auth for this endpoint?
@claude fix the TypeError in the user dashboard component
@claude review this PR for security issues

Claude 自动分析 context 并响应。

B. PR 打开时自动 review

on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR for code quality, correctness, and security. Post findings as review comments."
          claude_args: "--max-turns 5"

C. 定时跑(替代 cron 脚本)

on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  daily-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. Post as a discussion comment."
          claude_args: "--model opus"

D. issue 转代码

# 在 issue 里:
@claude implement #42
# Claude 读 #42 → 写代码 → 开 PR

E. 自定义 trigger phrase

with:
  trigger_phrase: "/ai"
  # 现在 @claude 改成 /ai 触发

4. claude_args — CLI 参数透传

Action v1 把 Claude Code CLI 的所有参数都开放给你:

claude_args: |
  --max-turns 5
  --model claude-opus-4-7
  --mcp-config /path/to/config.json
  --allowedTools "Read,Edit,Bash(git *)"
  --append-system-prompt "Follow our coding standards"

常用参数:

• --max-turns 5 — 防失控,默认 10
• --model claude-opus-4-7 — 这里就配模型(GHA 默认 Sonnet)
• --mcp-config path/to/.mcp.json — 装 MCP server(比如 Linear / Notion 连接)
• --allowedTools "..." — 工具白名单
• --debug — 排错时开

5. v1 GA vs beta 的破坏性改动(必看,如果你之前装过 beta)

旧(beta)	新(v1)
@beta	@v1
mode: "tag" 或 "agent"	删了 — 自动检测
direct_prompt: "..."	prompt: "..."
override_prompt: "..."	prompt: + GitHub 变量
custom_instructions: "..."	claude_args: --append-system-prompt "..."
max_turns: "10"	claude_args: --max-turns 10
model: "claude-sonnet-4-6"	claude_args: --model claude-sonnet-4-6
allowed_tools: "..."	claude_args: --allowedTools "..."
claude_env:	settings: JSON

升级路径:把 mode 字段删掉,把 direct_prompt → prompt,其他 flag 都进 claude_args,完成。

6. 3 种 provider 配置

直连 Claude API(最简单):

with:
  anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Amazon Bedrock(企业首选,数据驻留 AWS):

permissions:
  id-token: write  # OIDC 必须
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
      aws-region: us-west-2
  - uses: anthropics/claude-code-action@v1
    with:
      use_bedrock: "true"
      claude_args: '--model us.anthropic.claude-sonnet-4-6'

Google Vertex AI(企业首选,数据驻留 GCP):

permissions:
  id-token: write
steps:
  - uses: google-github-actions/auth@v2
    with:
      workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
      service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
  - uses: anthropics/claude-code-action@v1
    with:
      use_vertex: "true"
      claude_args: '--model claude-sonnet-4-5@20250929'

Bedrock / Vertex 路径比直连 API 多一层 OIDC 凭证管理,但凭证短命且不需要 hardcode。

7. 自定义 GitHub App(企业品牌化)

默认用 Anthropic 官方 GitHub App,所有 commit 显示成 “claude[bot]”。

如果想换成 “YourOrg Claude Assistant”:

1. github.com/settings/apps/new 建新 app
2. 权限:Contents R/W、Issues R/W、Pull requests R/W
3. 生成 private key → 存到 repo secrets 为 APP_PRIVATE_KEY
4. App ID → APP_ID
5. workflow 用 actions/create-github-app-token@v2 拿 token

适合企业;独立开发者用官方 App 就好。

8. CI 关键配置(CLAUDE.md)

repo 根目录的 CLAUDE.md 在 GitHub Actions 跑时自动加载(跟本地一样),指导 Claude 该项目的约定。

# Project conventions

## Style
- Tabs (not spaces)
- semicolons required
- functional components, no classes

## Testing
- Run `bun test` before pushing
- New features need tests
- Don't mock the database

写 CLAUDE.md = 配置 Claude 在 CI 里的行为。这是 GHA 集成跟其他 AI 代码工具最不同的地方:不是改 prompt,是改 repo 配置。

9. 成本警告(必看)

GHA 双重计费:

GitHub Actions minutes(GitHub 那边):

• 每次跑都消耗 runner minutes
• 公开 repo 免费 unlimited;私有 repo 看你 plan
• 长跑的 Claude 任务可能跑 5-10 分钟一个

Claude API tokens(Anthropic 那边):

• prompt + response 都计 token
• 复杂任务可能几十万 token
• Pro/Max 用户走订阅,不走 token billing

控制成本的策略:

claude_args: "--max-turns 5"   # 严格限步数
timeout-minutes: 10            # workflow 超时

concurrency:                    # 同时只跑一个
  group: claude-${{ github.ref }}
  cancel-in-progress: true

10. CI 不跑 Claude 的 commit? — 常见坑

GitHub 默认行为:用同一个 token 跑的 push 不会触发新 workflow。

要让 Claude 的 commit 触发 CI:

• 用 GitHub App(官方或自定义)token,不要用 ${{ secrets.GITHUB_TOKEN }}
• 确保你的 workflow on: 包含 push / pull_request 事件
• 检查 App 权限里有 CI 触发权

11. 跟 Claude Code on the Web 的 PR review 区别

Claude 还有一个自动 PR review 功能(/en/code-review):

	GitHub Actions	Web Code Review
触发	你定义 yaml	Claude 自动评论每个 PR
运行	GitHub runner	Anthropic 云
配置	claude_args + workflow	claude.ai 设置
适合	高度定制	零配置

简单说:普通 PR review → Code Review;复杂工作流 → GHA。

🟢 译者总评

1. GHA 是 Anthropic 把 “AI coder” 推进团队的关键产品

独立开发者还能用 claude CLI 解决问题。团队里要让 AI 工作必须:

• 不让某个人代表团队跟 AI 对话(那 Slack 上聊一聊就够了)
• 让 AI 参与代码评审、issue 处理、release 流程 — 必须走 CI
• 凭证管理、审计、回滚 — 都需要 git history

GHA 是这套需求的标准答案。Anthropic 不出 GHA 集成,就没法把 Claude Code 卖给 Fortune 500 的工程团队。

2. 给独立开发者的”够用”配方

如果你有 3-5 个 demo 项目,每个都装一份 claude.yml,作用:

场景	yml 内容
我开 PR 时自动 review	on: pull_request + prompt: "Review for quality / security / TS errors"
我 @claude fix 时去修	on: issue_comment
每周一早上写一份所有项目的 PR 摘要	on: schedule cron: 0 9 * * 1 + prompt: "summarize all open PRs"

总共 3 个 workflow,没什么维护成本,但工作流体验大幅提升。

3. v1 GA 是稳定信号 — 可以放心写到生产

@beta 期间 Anthropic 改动了 mode / direct_prompt / custom_instructions 等几个核心 API。v1 已经 GA,这些 API 不会再变。可以放心写到团队 workflow 里,不用担心半年后失效。

4. 警惕的反模式

• ❌ @claude 触发条件太宽(任意评论包含 “@claude” 字符串就触发)→ 容易误触
• ❌ 不设 --max-turns → Claude 可能跑 10+ turns,烧 quota
• ❌ 给 Claude bypassPermissions 类配置 → 在 CI 里没人监督,危险
• ❌ 不配 concurrency: cancel-in-progress → 一个 PR 改 10 次会跑 10 次 Claude
• ❌ 把 prompt 写得太抽象 → “review this PR” 不够,要说清审什么、不审什么

🔗 延伸阅读

• 同系列:09-routines-schedule.md(Routines vs GHA 取舍)、05-skills-system.md(GHA 也能加载 skill)、07-mcp-ecosystem.md(--mcp-config 把 MCP 接入 GHA)
• 官方 repo:https://github.com/anthropics/claude-code-action(examples/ 目录有 10+ 现成 workflow)
• 官方:/en/code-review — 零配置的 PR review 替代方案
• 官方:/en/gitlab-ci-cd — GitLab 版的等效集成

🔗 调研来源(可校验)

• 主原文:https://code.claude.com/docs/en/github-actions
• 官方 Action repo:github.com/anthropics/claude-code-action
• 官方 GitHub App:github.com/apps/claude
• v1 break changes 完整列表:本文档 “Breaking Changes Reference” 章节
• changelog 验证:/install-github-app 命令本机可用(本机 v2.1.139)