把 Claude Code 塞进 GitHub Actions,最省事的写法只有三步,第一次就能跑通,所以大多数仓库到这儿就停了。真正会咬人的地方,恰恰是这版最简配置没写出来的部分:提交是以谁的身份推的、作业令牌能干什么、除了你的团队还有谁能启动一次握着 API 密钥的运行。

打开网易新闻 查看精彩图片

这个动作叫 anthropics/claude-code-action@v1,在 Actions 作业里跑 Claude Code。不给 prompt 输入时,它等着被 @claude 提及;给了 prompt,它就在触发工作流的那个事件上直接跑。配置时要写 id-token: write,按模式给最窄的作业权限,并且用 Claude GitHub App 而不是 GITHUB_TOKEN,否则它推上去的提交不会触发 CI。

一次运行里其实有三道关卡:Claude 启动前的三项检查、两套彼此独立的认证,以及推送身份决定 CI 到底跑不跑。

两种模式,由一个输入决定

mode 输入已经取消,动作自己判断模式。没有 prompt 就是交互模式:它在 issue 或 PR 评论、PR 评审、新开 issue 的正文或标题里找触发词(默认 @claude),然后在一个持续更新的评论里回复。label_trigger(默认 claude)和 assignee_trigger 也能从标签或指派启动同一套流程。

设了 prompt 就是自动化模式:Claude 在任何事件上运行,包括 schedule,结果默认写进工作流运行日志而不是评论。纯文本 prompt 起步时既没有 shell 也没有 GitHub API 访问权,需要什么工具就在 claude_args 里用 --allowedTools 授予。作业上的 if: 不是装饰,它避免每条评论都拉起一个 runner,动作自己还会再核一遍触发词。

权限里 actions: read 出现两次是故意的。作业权限让令牌能读运行记录;additional_permissions 才是让动作启动 CI 工具(mcp__github_ci__get_ci_status、mcp__github_ci__get_workflow_run_details、mcp__github_ci__download_job_log)的开关。

认证是两个独立的问题

第一个问题是 Claude 怎么够到模型:Anthropic API 密钥、Claude 订阅的 OAuth 令牌、针对 Claude Console 服务账号的工作负载身份联合,或者 Amazon Bedrock、Google Cloud 的 Agent Platform(use_vertex)、Microsoft Foundry,各自走 OIDC。

第二个问题是动作怎么够到 GitHub:默认它申请一个 OIDC 令牌,拿去和 Anthropic 换一个 Claude GitHub App 的安装令牌,然后以 claude[bot] 的身份推送和评论。

两个答案都可能需要 id-token: write,所以这条权限出现在每个示例里。默认路径上漏了它,运行会停在“Could not fetch an OIDC token. Did you remember to add id-token: write to your workflow permissions?”。第一次提 PR 的人还会撞上第二条报错:工作流文件本身是新增或改动的时候,令牌交换会被拒绝,动作会记录说这是预期行为,合并 PR 之后工作流才开始工作。

用云厂商时,GitHub 身份要自己选:官方 App、只注册 Contents、Issues 和 Pull requests 三项权限的自定义 App,或者 GITHUB_TOKEN。官方 App 安装时带全套权限,包括 Actions 和 Workflows 的写权限,因为 GitHub 不允许只接受其中一部分;想把这个动作压到三项权限,就得走自定义 App。

身份还决定 CI 看不看得见 Claude 的活。用 GITHUB_TOKEN 推的分支不会触发 push 运行,所以任何会提交的工作流都得留着 App 或自定义 App 的令牌。

每个作业的最小权限

作业权限管的是作业自己的 GITHUB_TOKEN,不是动作换来的那个 App 令牌。这就是为什么 Anthropic 的代码评审示例里,作业只拿读权限加 id-token: write,却能发出行内评论——评论是用 Claude App 的令牌写的。只在 Claude 必须提交的地方给写权限,而且只给跑它的那个作业。

谁能启动它

Claude 启动前,动作会对操作者做两项检查。在 issue 和 PR 事件上,用户必须有写权限,没有的话会收到“Actor does not have write permissions to the repository”。在所有事件上(包括 schedule),机器人操作者会被拒绝,报错以“Workflow initiated by non-human actor:”开头,结尾提示把它加进 allowed_bots 列表,或者用 '*' 放行所有机器人。

这两个逃生口在动作自己的安全文档里都带警告。allowed_bots 里的机器人完全不检查仓库权限,所以在公开仓库上用 '*',等于任何能评论的 GitHub App 都能用自己控制的 prompt 驱动 Claude。allowed_non_write_users 绕过写权限检查,只在配了 github_token 时生效,而且只应该在作业权限小到只能打标签的场景里用。

对于作者没有写权限的 PR,restrict_untrusted_prs(默认开启)会禁掉那些从检出代码里跑命令的操作,哪怕 claude_args 里放行了也一样;Claude 仍然可以读、改、推。在公开仓库上,include_comments_by_actor 可以收窄哪些人的评论能进到 prompt 里。

常见问题

  • Claude 不回 @claude 评论?按顺序查:仓库装了 Claude GitHub App、API 密钥或 OAuth 令牌的 secret 存在、评论里的 @claude 是完整单词(不是 @claude-bot 也不是 /claude)、评论者有写权限。
  • 能用 Claude Max 订阅吗?可以。本地跑 claude setup-token,把结果存成 CLAUDE_CODE_OAUTH_TOKEN secret,传给 claude_code_oauth_token 输入而不是 anthropic_api_key;Pro、Max、Ultra、Team 和 Enterprise 套餐都在可列范围内,运行走订阅而不是 API 计费。跨仓库共享的 secret 要用 API 密钥,因为令牌绑定在生成它那个人的订阅上。
  • Bedrock 或 Vertex 能跑吗?能。设 use_bedrock: "true" 或 use_vertex: "true"(Foundry 是 use_foundry),先用云厂商自己的 OIDC 动作完成认证,给 id-token: write,再通过 claude_args 传模型 ID。

以上每个输入、默认值和报错信息,都读自 v1.0.273 版本的动作源码与 Anthropic 文档,不是一次录下来的运行日志。