Claude Code 接进 GitHub Actions
TL;DR: 官方 action anthropics/claude-code-action@v1 已经 GA,最常用的输入被收敛成三个:prompt(统一指令)、anthropic_api_key(Key)、claude_args(CLI 参数)。最小可用 workflow 只要二十来行:评论触发 + 仓库 Secret + 三个 permissions。本文给出可直接复制的 workflow、Secrets 怎么配、最小权限怎么写、PR 审阅场景长什么样,以及六个最常见的失败与对应修法。
一、两种接入形态:人找它,还是它自己跑
TL;DR: 评论触发是「人在 PR 里 @claude」;事件/定时触发是「PR 一开就自动跑」。前者权限最小、最好排查,后者最省人力、也最该控成本。
Claude Code 在 GitHub Actions 上有两条常见路子,选哪条决定了你的 workflow 长什么样:
- 评论触发(
issue_comment/pull_request_review_comment) —— 谁在 issue 或 PR 评论里@claude,谁就触发一次对话。适合「按需问一句」「让机器人解释某段 diff」。这是官方文档主推的起步形态。 - 事件或定时触发(
pull_request/schedule) —— PR 一开就自动审阅,或每天早上九点生成日报。适合「每次 PR 都要过一遍」「周期性报表」。这条路线会持续烧 token,必须配--max-turns和 workflow 超时。
新手最容易犯的错是两条一起上,然后被账单教育。先用评论触发跑通一次,再决定要不要上自动审阅。本机 Claude Code 还没跑通的话,先按开发者模式与 API 代理打通本地链路,再回来配 workflow。
二、最小可用 workflow(可直接复制)
TL;DR: 下面这段是评论触发的最小版本,拷进 .github/workflows/ 就能跑;Secret 名换成你自己的。
name: Claude Code
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
permissions:
contents: read
pull-requests: write
issues: write
jobs:
claude:
# 只有真的 @claude 才跑,避免每条评论都烧 token
if: contains(github.event.comment.body, '@claude')
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
回答这条评论里的问题,必要时读取仓库文件确认事实,
结论用中文写清楚,改动建议给到具体文件路径。
claude_args: "--max-turns 5 --model claude-sonnet-4-6"三个要点:prompt 是统一指令入口(v1 起 @claude 之外也能用它写任务);claude_args 承接 CLI 参数(--max-turns、--model、--append-system-prompt 都在这里);anthropic_api_key 只从 Secret 读,永远不要把 Key 写进 workflow 文件。用订阅账号的,把 Secret 换成 CLAUDE_CODE_OAUTH_TOKEN、输入换成 claude_code_oauth_token。
三、Secrets 怎么配:Key 从仓库设置进,不进代码
TL;DR: Key 存仓库 Secret(Settings → Secrets and variables → Actions),workflow 里只引用 ${{ secrets.XXX }};Key 写进仓库 = 泄露。
官方给的安装路径有两条:
- 快捷路径:在本机 Claude Code 里执行
/install-github-app,按提示装好 GitHub App 并创建所需 Secret。前提是你是仓库管理员。 - 手动路径:安装 Claude GitHub App(仓库权限:Contents 读写、Issues 读写、Pull requests 读写)→ 在仓库 Secret 里加
ANTHROPIC_API_KEY→ 把官方示例 workflow 拷进.github/workflows/。
两条路径的共同点是Key 只存在于 GitHub Secret 存储里,仓库里能看到的是引用而不是值。改 Key 也只需在 Secret 面板换一次,历史 run 不受影响。客户端配置(base URL、Key 字段)可以用客户端配置生成器生成,再把对应值填进仓库 Secret。
四、最小权限:三个 permissions 怎么给
TL;DR: 显式写 permissions: 块,别吃默认 token 的宽权限;Claude 要回评论才需要 issues: write 和 pull-requests: write。
工作流默认拿到的 GITHUB_TOKEN 权限范围可能比你想的宽,也可能比你想的窄。与其猜,不如在 workflow 顶部显式声明最小集:
permissions:
contents: read # 读代码
pull-requests: write # 发 review comment
issues: write # 回 issue 评论只读代码的场景,contents: read 就够;但只要让 Claude 把结论发回 PR 或 issue,就必须给 pull-requests: write / issues: write——少一个,常见表现是「评论没发出来」而不是显式报错。官方安全文档的建议也是:限制 action 权限到必要范围、人工复核 Claude 的建议再合并。
还有两条触发侧的硬检查,踩中直接失败而不是给提示:触发者要有仓库写权限——issue 与 PR 事件上,触发人没写权限就起不来(定时触发不看这条;要放开就配 allowed_non_write_users 并自备 github_token);触发者得是人——机器人账号会被拒,除非把它列进 allowed_bots,定时任务最容易撞这条,因为 GitHub 把定时 run 算到最后改过 cron 的那个用户名下。
五、PR 自动审阅:让它把结论发回 PR
TL;DR: 把触发器换成 pull_request,用 prompt 指定审阅维度,用 claude_args 限制轮次和模型;结论以 review comment 形式落在 PR 上。
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
permissions:
contents: read
pull-requests: write
issues: write
jobs:
review:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
审阅这个 PR:先看 diff,再按正确性、安全、性能三个维度找问题,
每条给出文件路径与行号,不要提风格偏好类建议。
claude_args: "--max-turns 5 --model claude-sonnet-4-6"这里的关键取舍是 --max-turns:它限制 Claude 最多自己走几步(工具调用轮次),是 CI 里最重要的一道成本闸门。想让它更克制就调小,想让它看得更细就调大,但每次调大都要重新掂量预算。审阅方法论本身(怎么定义评审标准、怎么分工人机)不在本文范围,见文末「相关阅读」里的治理篇。
六、六个常见失败与修法
TL;DR: 配置名搞混、权限不够、fork PR 没有 Secret、base URL 多写一层、模型名不存在、跑飞——六类问题各有一句修法。
- 照抄了 beta 的配置名。 v1 里
mode/direct_prompt/custom_instructions/max_turns已经并成prompt与claude_args(--max-turns、--append-system-prompt写在claude_args里),旧写法不再生效。 - 评论发不出来。 多半是
permissions没给pull-requests: write或issues: write。显式写permissions:块,别依赖默认 token。 - fork 来的 PR 里 Key 取不到。 GitHub 默认不向 fork PR 注入 Secret,这是保护机制不是 bug。要么把审阅放到评论触发,要么把「不审 fork PR」写成显式条件。
- base URL 多写了一层
/v1。 客户端自己会追加/v1/messages,多写一层就是 404。 - 模型名不存在。
--model的值必须是上游真实存在的模型 id,写错通常直接报错或回退到默认模型,不会提示你。 - 跑飞了。 CI 里没有人在旁边看着:加
--max-turns、加 workflow 级timeout-minutes、用 GitHub 的concurrency限制同一分支的并发 run。
七、CI 成本怎么控:三条闸门
TL;DR: token 是按量计的,CI 最容易失控。按「轮次 × 并发 × 超时」三道闸门设,就能把一次审阅的花费摁在可预期范围。
- 轮次闸门:
--max-turns直接决定单次 run 最多走多少步工具调用,是最有效的旋钮。 - 并发闸门:同一仓库多个 PR 同时开就同时跑,用
concurrency按分支串行化,避免尖峰。 - 超时闸门:workflow 级
timeout-minutes兜底,防止 agent 在一个 PR 上耗满额度。
再加一条经验:先用注释触发验证「Key、权限、模型」三件事都通,再打开自动审阅。反过来做,你会把配置错误和成本问题混在一起排查。
八、接同一个网关:CI 与本地共用一把 key
TL;DR: 把 ANTHROPIC_BASE_URL 指向 CodeGateway、Key 用同一把,CI 里换模型不用改流程,用量在看板里看得见。
如果你已经在用 CodeGateway 跑本地 Claude Code,CI 里也可以指向同一个网关:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.CODEGATEWAY_API_KEY }}
prompt: "审阅这个 PR,列出正确性问题并给出文件路径。"
claude_args: "--max-turns 5 --model claude-sonnet-4-6"
env:
ANTHROPIC_BASE_URL: https://api.codegateway.dev
ANTHROPIC_AUTH_TOKEN: ${{ secrets.CODEGATEWAY_API_KEY }}要点三条:ANTHROPIC_BASE_URL 不要带 /v1 后缀(客户端自己拼 /v1/messages);ANTHROPIC_AUTH_TOKEN 用 CodeGateway 的 Key,与 anthropic_api_key 输入填同一把;--model 换成网关目录里真实存在的模型 id。
这样做的价值有三层:一把 key 打通本地和 CI,不用为 CI 单独申请官方账号;同一把 key 下可以按场景换模型(审阅用 Sonnet、疑难件换 Opus),改的是 --model 而不是流程;每次 run 的输入输出 token 都落到 workspace 的用量与日志里,CI 花多少、哪个 PR 花得多,看板上一目了然。需要说明的是,CodeGateway 在官方价基础上按套餐档加价计费,不是官方价的直连价,具体倍率以定价页为准。
相关阅读
- Claude Code PR 治理方法论:怎么把评审标准写清楚 —— 本文只讲 CI 集成,治理方法论在那篇。
- Claude Code 快速上手 —— 本地跑起来的前置步骤。
- Claude Code MCP Server 配置 —— 让 Claude Code 在 CI 里接自己的工具。
现在就去领一把 key
没有官方 Key,或者不想绑外卡?⇒ 直接在 CodeGateway 领一个:注册即用,一把 key 打通 Claude / GPT / Gemini 等多家模型,按量计费、余额可查,CI 里换成自己的 Key 也只是改一行 Secret。注册与计费细节见定价页。
