2026-09-04·技能与命令

把 Claude Code 接入 GitHub Actions——@claude 提及、PR 评审、cron 三种触发，认证与权限、fork PR secrets 行为、可复制 workflow 模板，外加成本运营四抓手与多仓库推广治理清单。

把 Claude Code 接入 GitHub Actions：@claude 触发、PR 评审、定时巡检的完整 workflow

Q: GitHub App 和 claude-code-action workflow 有什么区别？

GitHub App 是凭证代理——管 OAuth、token 轮换、按 repo 划权限。action（anthropics/claude-code-action@v1）是跑在 workflow 里的代码。App 路径隐式调用 action；手写 workflow 路径让你能用自定义 trigger、prompt 和权限。两者重叠但并不重复。

Q: 能在自托管 runner 上跑吗？

可以。把 runs-on 改成 self-hosted 即可。Bedrock / Vertex 走 OIDC 的场景特别常见，因为自托管 runner 通常已经在 AWS / GCP 内网里、能直接 assume 云端 role。注意确保 runner 能访问 api.anthropic.com（或你用的 Bedrock / Vertex endpoint）。

Claude Code 的 GitHub Actions 集成是 Anthropic 官方一等公民，它让 Claude 直接出现在 issue 评论、PR 评审和定时任务里——而不只是本地终端的玩具。2025 年起 Anthropic 把 Claude Code 升级为 GitHub App 默认安装形态，配合官方 claude-code-action 可在 workflow 里直接跑 Claude。本文按 2026 年 8 月最新版本，整理三种最实用的接入模式（@claude mention、PR 评审触发、cron 定时巡检）、三种认证方式（API key、OAuth、OIDC）、四组必需权限，以及一份可直接复制粘贴的 workflow 模板。

TL;DR

三种触发模式：@claude mention / PR 评审自动触发 / cron 定时巡检

三种认证：API key（简单）、OAuth（多用户）、OIDC（Bedrock/Vertex IAM 推荐）

官方 action：anthropics/claude-code-action@v1 — GitHub App 默认安装形态

5 个必需权限：contents: read / issues: write / pull-requests: write / id-token: write / actions: read

2026 年新坑：@claude 必须小写、@ 直接接名字；fork PR 拿不到 secrets；OIDC 与 IAM role trust 关系

安装 GitHub App vs 手写 workflow

接入有两条路径。

第一条用 claude-code-action 仓库提供的一键安装。在仓库根目录运行：

> /install-github-app

Claude Code 会引导你走 OAuth，把 Anthropic GitHub App 装到目标仓库。这条路径只需要仓库 admin 权限，权限最小，最适合第一次接入。装好之后 anthropics/claude-code-action 已经以 GitHub App 身份跑，所有 secrets 都由 App 管理，仓库 settings 里看不到裸露的 ANTHROPIC_API_KEY。

第二条路径是在 .github/workflows/ 下手写 workflow 文件、用 anthropics/claude-code-action@v1 action。需要你自己配 secrets、permissions 与 trigger，适合自定义需求（比如限制触发者白名单、只允许 cron、跑在 fork 上）。两种方式可以并存——App 处理「人在评论里 @claude」，手写 workflow 处理 cron 巡检和定制化 PR 流程。

GitHub App 路径要仓库 admin 权限；手写 workflow 路径只需 contents:write。任何路径下都建议加 allowed_users 白名单，避免匿名用户滥用。

三种触发模式

按使用频率排序，最常见的三种触发如下。

模式一：@claude mention（人在环路）

监听 issue 评论或 PR 评论里有人写了 @claude ...。这是交互式模式，Claude 会读上下文、调用工具、改文件、跑测试、回一条评论。适合：让 Claude 修 bug、回答问题、补文档、做小范围重构。

模式二：PR opened / synchronized（自动化评审）

每次有 PR 打开或新 commit 推上来，Claude 自动审一遍，留行内评论与总结。适合：团队强制走一遍评审清单、检查风格与测试覆盖、抓常见坑。

模式三：cron 定时巡检

schedule: trigger，每天 / 每周定时跑 Claude 扫一遍 issue 列表、检查 CI 失败、生成周报。适合：长尾维护工作，避免人工记得去做。

下面给出三段可直接复制的 workflow。先做 @claude mention：

# .github/workflows/claude-mention.yml
name: Claude mention
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
      actions: read
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: claude_mention
          # 可选：限制谁能触发
          allowed_users: "octocat,monalisa"

trigger: claude_mention 是关键字段——只有评论里出现 @claude ... 才会唤醒，没提 Claude 的评论会被 action 直接跳过，不会浪费配额。

PR 评审模式

注：下面 YAML 里的 prompt: 是 claude-code-action 的输入字段（GitHub Actions 自身的字符串），不是 Claude API 的 prompt template。文字会原样传给 Claude 作为任务描述。

# .github/workflows/claude-pr-review.yml
name: Claude PR review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: pr_review
          # 自定义评审 prompt
          prompt: |
            请按以下清单评审此 PR：
            1. 是否破坏既有 API 契约
            2. 新增代码是否有对应测试
            3. 是否有未处理的 console.log / debugger
            4. 性能与并发安全
            把发现写成行内 review comment。

注意这里 contents: read 而不是 write——评审模式下 Claude 只读代码不写文件。如果你希望评审后 Claude 直接修，把 contents 升为 write。

Cron 定时巡检模式

同上：prompt: 是 action 的字符串输入，会原样作为任务描述传给 Claude。

# .github/workflows/claude-nightly.yml
name: Claude nightly sweep
on:
  schedule:
    - cron: "0 9 * * 1-5"   # 工作日 UTC 09:00

jobs:
  sweep:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: schedule
          prompt: |
            扫描仓库过去 24h 的 issue 与 PR：
            - 找出没人回应的、超过 3 天的 issue
            - 找出 CI 失败的 PR
            - 把结果写到 issues/nightly-report-<日期>.md 并贴一份到 #engineering 频道

cron 用 GitHub Actions 的 UTC 时间。本地时区与 UTC 的换算要在 cron 表达式里直接做（例如北京时间 17:00 = UTC 09:00）。

必需权限一览

把上面三段拼到一起看，可以归纳出四组必需权限——任何缺一项的 workflow 都会在第一次运行时立刻报错：

| 权限 | 用途 | 缺它会怎样 | |---|---|---| | contents: write | Claude 写文件、推 commit | 修 bug 模式直接失败 | | issues: write | 在 issue 下发评论、回 report | @claude mention 无法回复 | | pull-requests: write | 评审模式下留行内 comment | PR 评审直接无输出 | | id-token: write | OIDC 换取短期 token | Bedrock / Vertex / Foundry 后端连不上 | | actions: read | 读取 CI 状态做决策 | cron 巡检拿不到 build 结果 |

pull-requests: write 这一项常被漏掉——它不是「合并 PR」的权限，而是「在 PR 留 comment」的权限，名字有点反直觉。

三种认证方式

Claude Code action 需要一个 Anthropic 凭证才能跑。三种方式各有适用场景。

方式一：ANTHROPIC_API_KEY（最简单）

在仓库 Settings → Secrets 加一个 ANTHROPIC_API_KEY，action 默认会读它。适合个人 repo、小团队、低频使用。缺点：key 是长期凭证，一旦泄露需要手动 rotate。

方式二：CLAUDE_CODE_OAUTH_TOKEN（官方推荐）

通过 claude-code-action 走 OAuth 一次性授权。GitHub App 路径默认就是这种。短期 token，会自动 rotate。缺点：跨多 repo 不易共享。

方式三：OIDC（云端后端 + Bedrock/Vertex/Foundry）

- uses: anthropics/claude-code-action@v1
  with:
    trigger: claude_mention
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    # AWS Bedrock
    use_bedrock: true
    aws_region: us-east-1
    # 或 GCP Vertex
    use_vertex: true
    gcp_project_id: my-gcp-project
    gcp_region: us-central1

id-token: write 权限配合 cloud provider 的 OIDC trust policy，可以让 GitHub Actions 直接换出云端的短期凭证，无需长期 API key。适合：企业环境、合规要求严、要走 AWS/GCP 计费的团队。

安全：allowed_users 与 bot 过滤

@claude mention 模式下，任何有写评论权限的 GitHub 用户都能触发 Claude。这意味着被授予 write 的 collaborator、CI bot、或者被勾选了 "Allow edits from maintainers" 的外部贡献者都能唤醒 Claude，且每次触发都会消耗 token。

最小化风险的两条规则：

设置 allowed_users 白名单。填 GitHub 用户名（逗号分隔），不在名单里的 mention 会被 action 静默跳过。
配置 bot 过滤。github.event.comment.author_association 为 NONE 的评论直接拒绝——这挡掉了所有匿名用户和 fork 出来的 PR 评论。

- uses: anthropics/claude-code-action@v1
  with:
    trigger: claude_mention
    allowed_users: "octocat,monalisa,dependabot[bot]"
    # 自动过滤 NONE（匿名/fork）的评论

Fork PR 的 secrets 行为

GitHub Actions 一个老坑：从 fork 仓库发起的 PR 不会带着父仓库的 secrets 跑（出于安全），但 GitHub Actions 本身默认就会跑（也出于安全考虑，这两件事容易混淆）。

具体到 Claude Code action：

来自 fork 的 PR：action 仍会触发，但拿不到 ANTHROPIC_API_KEY；@claude mention 会失败但不会泄露任何凭证。
解决思路：对来自 fork 的 PR 走单独的 pull_request_target 触发（要小心 prompt injection），或者干脆只对仓库内成员开放触发（设 allowed_users 白名单）。

on:
  pull_request_target:   # 注意是 *_target，行为不同
    types: [opened]

pull_request_target 把 workflow 跑在父仓库上下文，能拿到 secrets，但代码本身也来自 PR——这是经典 prompt injection 入口。不推荐在没有充分沙箱化的 Claude 对话里用这条触发。

调试清单

Claude Code action 跑不出来时，按这份清单逐项排查：

看 action 的日志 —— 失败的 job 通常会打印 Claude 的 raw error，最常见的是认证错误与权限错误。
检查 workflow run 的 permissions —— GitHub UI 里 Settings → Actions → General，看「Workflow permissions」是不是设成 Read and write。如果设成 Read-only，上面的 contents: write 会被静默忽略。
确认 trigger 字符串匹配 —— @claude 必须是小写、@ 直接跟名字、名字与 action 默认的 trigger username 一致。@Claude（大写 C）不会触发。
看 allowed_users 拼写 —— GitHub 用户名区分大小写，Octocat 与 octocat 是两个账号。
网络问题 —— Bedrock/Vertex 模式下 id-token: write 权限缺失是头号原因；其次是 IAM role 没绑到 GitHub OIDC provider。
配额耗尽 —— API key 模式下，Anthropic 账户配额用完 action 会返回 429。OAuth 模式下 token 过期会自动 rotate，但如果整个 OAuth 关联被撤销，需要重跑 /install-github-app。

常见坑

坑 1：以为 GitHub App 装上就自动跑。App 装好默认不会跑任何 workflow——你仍然要在 .github/workflows/ 写文件、用 anthropics/claude-code-action@v1 触发。App 只是托管凭证。

坑 2：把 secrets 写进 workflow 文件。ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} 是合法写法，但绝不要把 key 硬编码到 workflow 文件里——一旦 PR 暴露，所有人都能读到。

坑 3：cron 表达式忘换时区。GitHub Actions 的 cron 是 UTC，写 0 9 * * * 是 UTC 09:00，不是北京时间 17:00。

坑 4：fork PR 上跑 Claude。默认会失败但不报错（被吞），容易让人以为配置有问题。看日志里 secrets are not available to forks 就是这个。

坑 5：在 PR 评论里贴长 prompt。@claude mention 的 prompt 来自评论正文——任何人都能写。@claude rm -rf / 这种 prompt injection 是真实风险，allowed_users 白名单是唯一可靠的防线。

实战：一条完整可用的 workflow

把上面所有点串成一条「团队日常能用」的 workflow：@claude mention + PR 自动评审 + 工作日 cron 巡检，三件套：

# .github/workflows/claude.yml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  pull_request:
    types: [opened, synchronize, ready_for_review]
  schedule:
    - cron: "0 9 * * 1-5"

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: ${{ github.event_name == 'schedule' && 'schedule' || github.event_name == 'pull_request' && 'pr_review' || 'claude_mention' }}
          allowed_users: "your-team,dependabot[bot]"

一份文件搞定三种触发模式。trigger: 字段根据触发的事件动态选择——schedule 走 cron 巡检，pull_request 走评审，其余评论类走 claude_mention。这是从「想让 Claude 进 CI」到「Claude 真的进了 CI」最短的路径。

成本运营：让 @claude 的账单可预测

每次 @claude 触发都是真实的 token 消耗，「能用」和「用得起」之间差一层运营。四个抓手，按见效快慢排序：

并发取消。 在 job 上加 concurrency:（同组新触发取消旧运行）——PR 连续 push 时只跑最新一次。这是唯一一个「配一行、立省一半」的抓手，应作为团队默认。

触发收窄。 allowed_users 白名单已经挡住了陌生人；进一步用 label 门控（只有打了 claude 标签的 issue/PR 才触发）能把「顺手 @ 一下」的试探性使用排除在外。cron 任务从每天一次起步，确认价值后再加密。

喂给它的上下文要节食。 token 消耗与 prompt 及工具调用成正比：巨型 CLAUDE.md、全仓库 attachments 都会直接放大账单。CI 场景给一份精简的专用 CLAUDE.md（只写构建、测试、约定），比复用交互式会话的那份便宜得多。

月度对账。 在 Anthropic Console 里给 CI 用的 key 单独建工作区或单独计费口径，月底按 workflow run 次数核对——异常上涨通常来自某个 PR 反复触发或 cron 密度失误，对账时一眼可见。

多仓库推广：组织级 rollout 治理清单

一个仓库跑通只是开始；推广到几十个仓库时，治理问题会集中爆发。上线前的六项检查：

审批入口唯一：GitHub App 的组织级安装由少数管理员持有，禁止个人随意给仓库加装——它等于给每个仓库发了一把 API key。
workflow 变更走 PR 评审：claude.yml 本身必须受分支保护——它能改触发条件、能读 secrets 作用域，是供应链意义上的敏感文件。
secrets 轮换策略成文：ANTHROPIC_API_KEY 的轮换周期、负责人、泄露后的撤销步骤，写进 oncall 手册；能用 OAuth token（CLAUDE_CODE_OAUTH_TOKEN）的团队优先用短生命周期凭据。
模板仓库分发：把验证过的 workflow 做成模板（或 org-level reusable workflow），新仓库复制而非手写——五个仓库五个版本的 claude.yml 是排障噩梦。
审计可查：workflow run 历史即审计日志，定期抽查「谁在什么上下文里触发了 Claude、改了什么」；配合仓库内的 allowed_users 名单一起看。
退出机制：预设降级路径——关掉 App 授权或删 workflow 即完全退出，不留隐性依赖（比如有人把 CI 结果写进了别处的工作流）。

常见问题

装了 GitHub App 后还需要保留 ANTHROPIC_API_KEY 吗？

不需要。App 路径用 OAuth 短期 token，由 Anthropic 的 GitHub App 托管——仓库 settings 里看不到裸 API key。如果你之后又加了手写 workflow（比如 cron 巡检），可以在「API key 写进 repo secrets」与「OAuth 走 CLAUDE_CODE_OAUTH_TOKEN」之间二选一。有合规或轮换要求就选 OAuth。

Fork PR 上能跑 Claude Code action 吗？

能跑，但拿不到父仓库的 secrets。action 仍然触发，Claude 无法认证到 Anthropic，结果是「静默失败」。安全的做法是 (a) 用 allowed_users 白名单限制只有 repo 成员能触发，或 (b) 用 pull_request_target 触发（接受 prompt injection 风险）。对大多数团队，(a) 更稳妥。

GitHub App 和 claude-code-action workflow 有什么区别？

GitHub App 是凭证代理——管 OAuth、token 轮换、按 repo 划权限。action（anthropics/claude-code-action@v1）是跑在 workflow 里的代码。App 路径隐式调用 action；手写 workflow 路径让你能用自定义 trigger、prompt 和权限。两者重叠但并不重复。

GitHub Actions 跑 Claude 的成本怎么算？

每次成功的 Claude Code action 运行，按 prompt 长度与工具调用数消耗 Anthropic token——大致与本地跑同一任务相当。失败的运行（认证错、权限错）不消耗 token。想控制成本：(a) allowed_users 白名单挡住随机评论；(b) 给 job 加 concurrency: 取消旧 run。

能在自托管 runner 上跑吗？

可以。把 runs-on 改成 self-hosted 即可。Bedrock / Vertex 走 OIDC 的场景特别常见，因为自托管 runner 通常已经在 AWS / GCP 内网里、能直接 assume 云端 role。注意确保 runner 能访问 api.anthropic.com（或你用的 Bedrock / Vertex endpoint）。

官方参考资料

本文基于截至 2026 年 8 月的公开信息，workflow 语法与 action flag 会演进；为保持 CI 稳定，请 pin 到 major 版本（如 @v1），不要用 @main。