GitHub Actions

Claude Code GitHub Actions 是在你仓库的工作流里运行 Claude Code 的 GitHub Action。在 PR 或 issue 评论里提及 @claude，就能让 Claude 分析代码、实现改动并推送提交。你也可以给它一个 prompt，让它在任意 GitHub 事件（包括定时任务）上自动运行。

多个产品共用 Claude Code 这个名字。本页讲的是 claude-code-action 工作流集成，通过仓库里的工作流文件配置。相关产品：Code Review（每个 PR 自动评审，无需写工作流）、云端的 Claude Code、Claude Agent SDK（GitHub Actions 之外的自定义自动化，本 Action 就构建在 SDK 之上）、GitHub Enterprise Server。

安装

两种方式，两种都需要仓库的管理员权限：

• 快速安装：在 Claude Code 里运行 /install-github-app。Claude Code 会安装 GitHub App、添加认证 secret，并为你准备好工作流 PR
• 手动安装：自己安装 App、添加 secret、把工作流文件复制进仓库。适用于你不在本地运行 Claude Code、命令失败、或想完全控制工作流文件的情况

快速安装

/install-github-app 只适用于 github.com 仓库（如果 git 远程在 gitlab.com 或 bitbucket.org，它会打印提示后退出；GitLab 见 Claude Code GitLab CI/CD）。开始前先安装 GitHub CLI 并用 gh auth login 认证。

在要连接的仓库里打开 claude，运行 /install-github-app 并按提示操作。Claude Code 会安装 Claude GitHub App，然后为工作流设置认证 secret：已有 API Key 时复用它；否则可选择用你的 Claude 订阅创建长期令牌，或粘贴 API Key。凭据会存成仓库 secret：API Key 对应 ANTHROPIC_API_KEY，订阅令牌对应 CLAUDE_CODE_OAUTH_TOKEN。

然后 Claude Code 推送一个带有你所选工作流文件（已指向该 secret）的分支，并在浏览器里打开 GitHub，PR 已准备好创建。创建并合并这个 PR，@claude 就在仓库里生效了。快速安装适用于 Claude API 和 Claude 订阅；用 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 的，见官方「Use Claude Code GitHub Actions with cloud providers」。

手动安装

1. 把 Claude GitHub App 安装到你的仓库。Action 依赖 App 的三个权限：Contents（读写，让 Claude 能修改仓库文件）、Issues（读写，响应 issue）、Pull requests（读写，创建 PR 并推送改动）
2. 向仓库添加一个 secret：ANTHROPIC_API_KEY（来自 Claude Console 的 API Key），或 CLAUDE_CODE_OAUTH_TOKEN（用你的 Claude 订阅认证的 OAuth 令牌，Pro、Max、Team、Enterprise 套餐可用，在本地运行 claude setup-token 生成）。在工作流文件里，API Key 传给 anthropic_api_key 输入，OAuth 令牌传给 claude_code_oauth_token 输入
3. 把官方示例仓库里的 examples/claude.yml 复制到仓库的 .github/workflows/ 目录

安装后，在 issue 或 PR 评论里 @claude 来测试。

为组织安装

快速和手动安装一次只配置一个仓库。要在整个组织推广：在组织级别安装一次 Claude GitHub App（选所有仓库或指定列表）；把认证 secret 存为组织级 Actions secret；给每个要运行的仓库添加工作流文件，或把作业定义成一个各仓库调用的可复用工作流。跨仓库共享的 secret 用 Console 里的 API Key 而不是 OAuth 令牌，因为 OAuth 令牌绑定的是运行 claude setup-token 那个人的订阅。想完全避免保存长期 secret，可以用工作负载身份联合（workload identity federation），Action 把工作流的 GitHub OIDC 令牌通过 Claude Console 服务账号换成 Claude API 访问权限，需要给工作流 id-token: write 权限。

卸载

删除 .github/workflows/ 里使用 anthropics/claude-code-action 的工作流（快速安装会有 claude.yml，选了评审工作流则还有 claude-code-review.yml）；删除仓库（以及共享时的组织级）里的 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN secret（删除 secret 不会让凭据失效，要彻底弃用 API Key 还要去 Console 删除）；如果你不为其他 Claude 功能（如 Code Review 或网页自动修复）使用，再到 GitHub 设置的 GitHub Apps 里卸载 Claude GitHub App。

GitHub App 权限

Claude GitHub App 由所有与 GitHub 集成的 Claude 功能共用。安装时你授予：Actions（读写）、Checks（读写）、Contents（读写）、Discussions（读写）、Issues（读写）、Members（读）、Metadata（读）、Pull requests（读写）、Repository hooks（读写）、Statuses（读）、Workflows（读写）。GitHub 不允许只接受其中一部分；如果你的组织只想要 Action 用到的权限，可以按官方设置指南创建只含 Contents、Issues、Pull requests 的自定义 GitHub App。

交互模式与自动化模式

Action 根据你的工作流配置检测运行方式：

• 交互模式：工作流没有提供 prompt 输入时，Claude 等待触发短语（默认 @claude）出现在 issue 或 PR 评论、PR 评审，或新开 issue 的正文或标题里，然后响应该请求。进度和结果显示为 issue 或 PR 上的评论
• 自动化模式：工作流提供了 prompt 输入时，Claude 不等待提及就运行，只受「谁能触发运行」检查的约束。默认结果出现在工作流运行日志里而不是评论里

谁能触发运行：两种模式下，Action 都会在 Claude 启动前对触发者做两项检查，任何一项拒绝都会使运行失败：

• 写权限：对 issue 和 PR 事件，触发用户必须对仓库有写权限（要允许没有写权限的特定用户，设置 allowed_non_write_users 并传入你自己的 github_token；没有用户作者的事件如 schedule 跳过此检查）
• 人类触发者：对所有事件，Action 都拒绝机器人触发者，除非你把它列在 allowed_bots 里，防止机器人让 Claude 陷入循环

示例用例

官方仓库的 examples 目录里有适用于不同场景的现成工作流。下面的示例使用 API Key 认证；如果用 Claude 订阅认证，把 anthropic_api_key 那一行换成 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}。

响应 @claude 提及

这个工作流以交互模式运行 Action，任何人在 issue 或 PR 评论里提及 @claude 时 Claude 都会响应：

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

这个工作流里非样板的部分：id-token: write 是 Action 默认的 GitHub App 认证所必需的；actions: read 让 Claude 能读取 PR 上的 CI 结果；actions/checkout 给 Claude 一份仓库的本地副本；if 让运行器不在没提 @claude 的评论上启动。有了工作流后，在任何 issue 或 PR 评论里带着请求提及 @claude：

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

Claude 在同一 issue 或 PR 里回复评论，并随着工作进展更新它。

运行 Skill

prompt 输入既接受纯文本，也接受 Skill 调用。仓库 .claude/skills/ 里的 Skill，要在 anthropics/claude-code-action 步骤之前运行 actions/checkout，让 Skill 文件在运行器上可用，然后把 /skill-name 作为 prompt；打包在插件里的 Skill，用 plugin_marketplaces 和 plugins 输入安装插件，再把带命名空间的 /plugin-name:skill-name 作为 prompt。

下面的工作流安装 code-review 插件，并在 PR 被打开、更新、重新打开或标记为可评审时运行其 Skill：

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

两行控制评审去向：--comment 让 Claude 把评审发到 PR 上（找到的每个问题一条行内评论，没问题则一条总结评论），没有它 Claude 什么都不发，你只能在工作流运行日志里读到发现；claude_args 这一行要保留，即使 Skill 自己的 allowed-tools 前置信息也列了同一个工具，因为只有 claude_args 里的 --allowedTools 点名它，Action 才会启动发行内评论的 MCP 服务器。Claude 会跳过草稿和已关闭的 PR、它判断不需要评审的 PR（如自动生成的或琐碎的）以及已经有 Claude 评论的 PR。

按计划运行

带 prompt 输入时，Action 在任意 GitHub 事件（包括 cron 计划）上以自动化模式运行。对纯文本提示，在你用 claude_args 里的 --allowedTools 授予所需工具之前，Claude 没有 shell 或 GitHub API 访问权限。这个工作流每天 09:00 UTC 在工作流运行日志里生成一份报告：

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    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"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

最佳实践

• 在 CLAUDE.md 里定义项目标准：在仓库根目录创建 CLAUDE.md，定义代码风格、评审标准、项目特定规则和偏好的模式，Claude 创建 PR 和响应请求时会遵循
• 保护你的凭据：永远不要把 API Key 或 OAuth 令牌直接提交到仓库，始终存为 GitHub Secrets 并在工作流里引用，例如 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}；只给工作流授予它需要的权限，并在合并前审阅 Claude 的改动
• 管理成本：每次运行消耗两种资源：GitHub Actions 分钟数（在 GitHub 托管的运行器上运行）和 API token。降低成本的办法：写具体的 @claude 请求，让 Claude 需要更少回合；用 issue 模板预先提供上下文；保持 CLAUDE.md 简洁（每次运行都会读）；在 claude_args 里设置 --max-turns 限制迭代次数；设置工作流级超时避免失控的作业；用 GitHub 的并发控制限制并行运行

使用云厂商

默认 Action 用你的 API Key 或 OAuth 令牌直接调用 Claude API。想让推理走你自己的云账号，设置对应厂商的输入：Amazon Bedrock 用 use_bedrock: "true"，Google Cloud 的 Agent Platform 用 use_vertex: "true"，Microsoft Foundry 用 use_foundry: "true"。三家都通过 OIDC 身份联合认证，而不是 Claude API Key，所以仓库里不存静态云凭据。

排障

Claude 不响应 @claude 命令：确认 GitHub App 已安装到仓库；检查仓库已启用工作流；确保 API Key 或 OAuth 令牌已设置在仓库 secret 里；确认评论里 @claude 是个完整的词，而不是 /claude 或 @claude-bot；确认评论用户对仓库有写权限。

CI 没有在 Claude 的提交上运行：GitHub 不会对用默认 GITHUB_TOKEN 做出的提交触发工作流。如果你给 Action 传了 github_token: ${{ secrets.GITHUB_TOKEN }}，把它去掉让它以 Claude GitHub App 的身份认证，或者传一个自定义 App 令牌；同时检查你的 CI 工作流触发器包含 Claude 推送所产生的事件（如 push 或 pull_request）。

认证错误：先在本地用 claude 测试，确认 API Key 或 OAuth 令牌有效，再去排查工作流；Bedrock、Agent Platform 和 Foundry 见对应云厂商页面的排障部分。

高级配置

Action 参数

最常用的输入，每个对应 anthropics/claude-code-action 步骤里的一个 with: 键：

传递 CLI 参数

claude_args 接受任何 Claude Code CLI 参数：

claude_args: "--max-turns 5 --model claude-sonnet-5 --mcp-config /path/to/config.json"

常用参数：--max-turns（限制对话回合数）、--model（使用的模型，如 claude-sonnet-5；不带此参数则用 Claude Code 默认模型）、--mcp-config（MCP 配置路径）、--allowedTools（允许的工具，逗号分隔）、--debug（启用调试输出）。

从 beta 升级

如果你的工作流仍引用 anthropics/claude-code-action@beta，更新到 v1：把 uses 行里的 @beta 改成 @v1；去掉 mode 输入（Action 现在自动检测模式）；把 direct_prompt 换成 prompt。