← 返回博客

Claude Code 接进 GitHub Actions:配置、Secrets 与 PR 自动审阅

(Unofficial)

本指南由社区独立维护,与被介绍的第三方工具厂商无官方隶属、背书或赞助关系,不代表其官方文档。文中第三方商标归其各自所有者所有。

2026年11月12日
Claude Code 接进 GitHub Actions:配置、Secrets 与 PR 自动审阅

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 长什么样:

  1. 评论触发(issue_comment / pull_request_review_comment) —— 谁在 issue 或 PR 评论里 @claude,谁就触发一次对话。适合「按需问一句」「让机器人解释某段 diff」。这是官方文档主推的起步形态。
  2. 事件或定时触发(pull_request / schedule) —— PR 一开就自动审阅,或每天早上九点生成日报。适合「每次 PR 都要过一遍」「周期性报表」。这条路线会持续烧 token,必须配 --max-turns 和 workflow 超时。

新手最容易犯的错是两条一起上,然后被账单教育。先用评论触发跑通一次,再决定要不要上自动审阅。本机 Claude Code 还没跑通的话,先按开发者模式与 API 代理打通本地链路,再回来配 workflow。

二、最小可用 workflow(可直接复制)

TL;DR: 下面这段是评论触发的最小版本,拷进 .github/workflows/ 就能跑;Secret 名换成你自己的。

yaml
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 顶部显式声明最小集:

yaml
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 上。

yaml
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 多写一层、模型名不存在、跑飞——六类问题各有一句修法。

  1. 照抄了 beta 的配置名。 v1 里 mode / direct_prompt / custom_instructions / max_turns 已经并成 prompt 与 claude_args(--max-turns、--append-system-prompt 写在 claude_args 里),旧写法不再生效。
  2. 评论发不出来。 多半是 permissions 没给 pull-requests: write 或 issues: write。显式写 permissions: 块,别依赖默认 token。
  3. fork 来的 PR 里 Key 取不到。 GitHub 默认不向 fork PR 注入 Secret,这是保护机制不是 bug。要么把审阅放到评论触发,要么把「不审 fork PR」写成显式条件。
  4. base URL 多写了一层 /v1。 客户端自己会追加 /v1/messages,多写一层就是 404。
  5. 模型名不存在。 --model 的值必须是上游真实存在的模型 id,写错通常直接报错或回退到默认模型,不会提示你。
  6. 跑飞了。 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 里也可以指向同一个网关:

yaml
      - 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 在官方价基础上按套餐档加价计费,不是官方价的直连价,具体倍率以定价页为准。

相关阅读

现在就去领一把 key

没有官方 Key,或者不想绑外卡?⇒ 直接在 CodeGateway 领一个:注册即用,一把 key 打通 Claude / GPT / Gemini 等多家模型,按量计费、余额可查,CI 里换成自己的 Key 也只是改一行 Secret。注册与计费细节见定价页。

作者:CodeGateway 团队最后审稿:2026-11-05

用 CodeGateway 解决 API 密钥与限流难题

缺少官方 API Key 或面临海外信用卡支付受限?注册立得 sk-cg- 密钥,支持 Claude、GPT、Gemini、DeepSeek。注意:Claude 与 Gemini 的文本模型走 Anthropic Messages 协议(/v1/messages),OpenAI 兼容的文本端点不接收这两系。内置智能路由、用量分析与免费体验额度。

免费注册