用法

Claude Code GitHub Actions 配置教程：在 Issue 和 PR 里 @claude

发布于 2026 年 10 月 30 日 · 最后核对 2026 年 10 月 30 日

Claude Code GitHub Actions 是一个在仓库工作流里运行 Claude Code 的 GitHub Action：在 PR 或 Issue 评论里 @claude，Claude 就会分析代码、实现修改并推送提交。这一页是配置步骤：快速安装和手动安装各怎么做、基本工作流怎么写、常用参数、谁能触发、费用和安全注意事项，以及不响应时看什么。内容按 Anthropic 的 Claude Code GitHub Actions 中文整理，2026 年 10 月 30 日对照原文核对。

它能做什么

Claude Code GitHub Action 在仓库的工作流里运行 Claude Code。在 PR 或 Issue 评论里提及 @claude，Claude 会分析代码、实现修改并推送提交。你也可以给它一个 prompt，让它在任意 GitHub 事件上自动运行。官方文档列出的用途有：把 Issue 变成 PR、根据评论修 bug、自动化重复任务。

几个产品都叫 Claude Code。本页讲的是用仓库里的工作流文件配置的 claude-code-action。如果你只想要每个 PR 都自动审查而不写工作流，官方文档指向的是另一个产品 Code Review。

配置：快速安装和手动安装

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

快速安装

/install-github-app 只支持 github.com 仓库。如果仓库的 git remote 在 gitlab.com 或 bitbucket.org，命令会打印提示并退出，不会开始安装。

1. 安装 GitHub CLI，并用 gh auth login 登录。Claude Code 会检查它，缺失时给出警告。
2. 在要连接的仓库里打开 claude，运行 /install-github-app，按提示操作。Claude Code 先安装 Claude GitHub App，再为工作流设置认证密钥。
3. 认证密钥的选择：如果 Claude Code 已经有 API key，会直接复用，并且在仓库里已有 ANTHROPIC_API_KEY 密钥时询问是否保留；否则在“用你的 Claude 订阅创建长期令牌”和“粘贴 API key”之间二选一。
4. Claude Code 把凭据存成仓库密钥：API key 对应 ANTHROPIC_API_KEY，订阅令牌对应 CLAUDE_CODE_OAUTH_TOKEN。
5. Claude Code 推送一个带有你所选工作流文件的分支，文件已经设为使用这个密钥，并在浏览器里打开 GitHub，PR 已经准备好。创建并合并这个 PR，仓库里就可以用 @claude 了。

想中途停止，按 Esc：正在进行的步骤会做完，之后的步骤不再开始，结束时的消息会列出仓库里已经发生的事，比如已推送的分支或已保存的密钥。安装 GitHub App 之后，Claude Code 会问是否继续 GitHub Actions 的设置；选 Skip for now 就只装 App，之后再运行 /install-github-app 完成工作流和密钥两步。

如果你选了审查工作流，Claude 会把每条审查发在 PR 本身：发现的每个问题发一条行内评论，没发现问题就发一条汇总评论。Claude 会跳过一些 PR，比如草稿。v2.1.229 之前，Claude 只把审查写进工作流运行日志。

要更新早期版本生成的审查工作流，二选一：

• 再次运行 /install-github-app。仓库里已有 claude.yml 时，选 Update workflow file with latest version。Claude Code 把新的工作流文件推到一个新分支并开 PR，和第一次安装一样。
• 自己把下文审查工作流示例里的 --comment 参数和 claude_args 那一行加进已提交的文件，这样能保留你对文件做过的其他修改。

如果你用的是 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry，官方文档把你指向另一页：Use Claude Code GitHub Actions with cloud providers。

手动安装

1. 安装 Claude GitHub App。把 Claude GitHub App 安装到仓库。这个 Action 依赖 App 的三项权限：

• Contents：读写，Claude 才能修改仓库文件。
• Issues：读写，Claude 才能回应 Issue。
• Pull requests：读写，Claude 才能创建 PR 并推送改动。

安装时你还会授予其他 Claude 功能用到的权限，完整列表见下文“GitHub App 权限”。

2. 添加认证密钥。按你的认证方式，在仓库里添加下面其中一个密钥。GitHub 的做法见 using secrets in GitHub Actions。

• ANTHROPIC_API_KEY：来自 Claude Console 的 Claude 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 就会响应，并使用 ANTHROPIC_API_KEY 密钥认证。如果你添加的是 CLAUDE_CODE_OAUTH_TOKEN，把工作流里的 anthropic_api_key 那一行改成 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}。

安装完成后，在 Issue 或 PR 评论里 @claude 测试一下。

为整个组织配置

快速安装和手动安装一次只配一个仓库。要在组织里推广：

• 在组织层面安装一次 Claude GitHub App，选全部仓库或一个选定的列表。
• 把认证密钥存成组织级别的 Actions 密钥，每个仓库不用各存一份。
• 给每个要运行这个 Action 的仓库加上工作流文件，或者把作业定义成一个可复用工作流，让各仓库调用。

跨仓库共享的密钥，用 Claude Console 的 API key，不要用 OAuth 令牌，因为 OAuth 令牌绑定的是运行 claude setup-token 那个人的订阅。想完全不存长期密钥，可以用工作负载身份联合：Action 把工作流的 GitHub OIDC 令牌通过 Claude Console 的服务账号换成 Claude API 访问。需要设置的输入是 anthropic_federation_rule_id、anthropic_organization_id，以及可选的 anthropic_service_account_id 和 anthropic_workspace_id，并给工作流 id-token: write 权限。Console 一侧的配置见 Action 的 setup 指南。

GitHub App 权限

Claude GitHub App 由所有接入 GitHub 的 Claude 功能共用，包括这个 Action、Code Review，以及云端会话里的 PR 自动修复。一个 GitHub App 只有一套权限，所以其中有些权限这个 Action 并不使用。安装时你会授予：

安装 App 就是接受它的全部权限，GitHub 不允许只接受一部分。如果你的组织只允许这个 Action 用到的权限，可以按 Action 的 setup 指南创建一个只有 Contents、Issues 和 Pull requests 的自定义 GitHub App。自定义 App 只覆盖这个 Action，Code Review 和网页端自动修复仍然需要官方 App。

基本工作流：响应 @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 的评论上启动 runner。Action 在响应之前也会自己检查触发短语。

工作流就位后，在任意 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 里用一条评论回复，并在工作过程中更新它。

交互模式、自动化模式和谁能触发

Action 根据工作流配置判断怎么运行：

• 交互模式：工作流没有 prompt 输入时，Claude 等待触发短语（默认是 @claude），可以出现在 Issue 或 PR 评论里、PR 审查里，或者新开 Issue 的正文或标题里，然后响应这个请求。进度和结果以评论形式出现在触发它的 Issue 或 PR 上。
• 自动化模式：工作流提供了 prompt 输入时，Claude 不等提及就运行，只受下面“谁能触发”的检查限制。默认情况下，结果出现在工作流运行日志里，而不是评论里。如果 prompt 指示它发帖，并且它有能发帖的工具，Claude 可以发到 Issue 或 PR 上。

两种模式下，Action 在 Claude 启动之前都会对触发者做两项检查，任何一项不通过，运行就失败：

• 写权限：对 Issue 和 PR 事件，触发的用户必须对仓库有写权限。要放行没有写权限的特定用户，设置 allowed_non_write_users 并传入你自己的 github_token 输入。没有用户作为作者的事件，比如 schedule 触发，跳过这一项检查。
• 人类触发者：对每种事件，Action 都会拒绝 bot 触发者，除非你把它列在 allowed_bots 里，以免 bot 让 Claude 陷入循环触发。这项检查同样适用于定时运行：GitHub 把定时运行算到某个仓库用户头上，通常是最后改过工作流 cron 的那个人；如果这个用户是 bot，就把它列进 allowed_bots。

常用参数

这些是最常用的输入，每个都对应 anthropics/claude-code-action 这一步里的一个 with: 键。

完整的输入列表见 Action 的配置参考。

用 claude_args 传 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。不传这个参数时，Action 使用 Claude Code 的默认模型。
• --mcp-config：MCP 配置的路径。
• --allowedTools：允许使用的工具，逗号分隔。--allowed-tools 这个别名也可以用。
• --debug：开启调试输出。

更多用法示例

官方的 examples 目录里有各种场景的现成工作流。本页的示例都用 API key 认证；如果你用 Claude 订阅认证，把任何示例里的 anthropic_api_key 那一行换成 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}。

在 PR 上自动审查（运行技能）

prompt 输入除了纯文本，也接受技能调用：

• 仓库 .claude/skills/ 目录里的技能：在 anthropics/claude-code-action 这一步之前运行 actions/checkout，让技能文件在 runner 上可用，然后把 /skill-name 作为 prompt。
• 打包在插件里的技能：用 plugin_marketplaces 和 plugins 输入安装插件，然后把带命名空间的 /plugin-name:skill-name 作为 prompt。plugins 输入的格式是 plugin-name@marketplace-name，其中市场名来自市场自己的清单，而不是它的仓库 URL。

下面的工作流安装 code-review 插件，并在 PR 被打开、更新、重新打开或标记为可审查时运行它的技能。它和快速安装里的审查工作流用的是同一个插件。想自己控制 prompt、模型和触发条件时用这样的工作流。在公开仓库里，GitHub 不会把密钥交给 fork 的 PR 触发的运行，所以这个审查只会在同一仓库分支发起的 PR 上运行。

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-plugins-official.git"
          plugins: "code-review@claude-plugins-official"
          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：即使技能自己的 allowed-tools frontmatter 已经列出同一个工具，也要保留这一行，因为只有 claude_args 里的 --allowedTools 点名了它，Action 才会启动发行内评论的 MCP 服务器。

Claude 会跳过草稿和已关闭的 PR、它判断不需要审查的 PR（比如自动生成的或很小的改动），以及已经有 Claude 评论的 PR。

按计划运行

有 prompt 输入时，Action 在任意 GitHub 事件上以自动化模式运行，包括 cron 定时。对纯文本 prompt，在你授予 prompt 所需的工具之前，Claude 没有 shell 或 GitHub API 的访问权限：用 claude_args 里的 --allowedTools，或 settings 输入里的 permissions.allow 规则。如果调用的是技能，Claude 可以使用技能 allowed-tools frontmatter 授予的工具。GitHub 只从默认分支运行定时工作流，并且在公开仓库里，仓库 60 天没有活动后会停用定时。

下面的工作流每天 09:00 UTC 在工作流运行日志里生成一份报告。它的 claude_args 选定模型并允许两个 GitHub MCP 工具。Claude 通过这些工具经 GitHub API 读取提交和 Issue，所以可以省掉 checkout 步骤：

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 和响应请求时会遵循这些规范。CLAUDE.md 的写法见 CLAUDE.md 配置。

安全：密钥和权限

警告：永远不要把 API key 或 OAuth 令牌直接提交进仓库。始终把它们存成 GitHub Secrets，并在工作流里引用，例如 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}。

• 只给工作流它需要的权限，并在合并之前检查 Claude 的改动。
• 要让这个 Action 在不存长期密钥的情况下认证，可以用上文的工作负载身份联合。
• 删除密钥并不会让凭据失效：要彻底停用一个 API key，还要在 Claude Console 里删除这个 key。
• 权限和认证方面更详细的指导，见 Claude Code Action 安全文档。数据处理和保留问题见官方的 data usage 和 security 页面。

想给 Claude 的工具使用加规则，可以参考 权限模式 和 Hooks 两篇，它们讲的是 Claude Code 本身的机制。

费用和用量

每次运行消耗两类资源：

• GitHub Actions 分钟数：Action 运行在 GitHub 托管的 runner 上，消耗你的 Actions 分钟数。价格和分钟数上限见 GitHub 的计费文档。
• API token：每次交互消耗的 token 取决于 prompt 和回复的长度、任务复杂度和代码库大小。当前 token 价格见 Claude 的定价页。如果你用 OAuth 令牌认证，运行使用的是你的 Claude 订阅，而不是 API 计费。

想同时降低两类成本，给 Claude 更清晰的上下文，并限制每次运行的工作量：

• 把 @claude 的请求写具体，Claude 需要的轮数就更少。
• 用 Issue 模板把上下文提前给全。
• 让 CLAUDE.md 保持简短，因为 Claude 每次运行都会读它。
• 在 claude_args 里设置 --max-turns 限制迭代次数。
• 设置工作流级别的超时，避免作业失控。
• 用 GitHub 的并发控制限制并行运行数。

常见问题排查

Claude 不响应 @claude

• 确认 GitHub App 已安装在这个仓库上。
• 检查仓库已启用工作流。
• 确认你的 API key 或 OAuth 令牌已设置在仓库密钥里。
• 确认评论里的 @claude 是一个完整的词，不是 /claude 或 @claude-bot。
• 确认评论的用户对仓库有写权限，例外情况见上文“谁能触发”。

Claude 的提交没有触发 CI

• GitHub 不会对用默认 GITHUB_TOKEN 做的提交触发工作流。如果你给 Action 传了 github_token: ${{ secrets.GITHUB_TOKEN }}，删掉它，让 Action 以 Claude GitHub App 的身份认证，或者改传一个自定义 App 的令牌。
• 检查你的 CI 工作流的触发条件包含 Claude 推送产生的事件，比如 push 或 pull_request。

认证错误

• 在调试工作流之前，先在本地用 claude 测试，确认 API key 或 OAuth 令牌有效。
• Bedrock、Agent Platform 和 Foundry 的认证问题，看云服务商那一页的排错部分。

更多解决办法见 Action 的 FAQ。

卸载和从 beta 升级

• 工作流文件：删除 .github/workflows/ 里使用 anthropics/claude-code-action 的工作流。用快速安装的话，找 claude.yml，选了审查工作流的话还有 claude-code-review.yml。
• 密钥：从仓库里删除 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN 密钥，如果共享给了多个仓库，也要从组织级别的 Actions 密钥里删除。
• GitHub App：在仓库或组织设置的 GitHub Apps 下卸载 Claude GitHub App，但前提是你没有把它用于其他 Claude 功能，比如 Code Review 或网页端自动修复。
• 如果工作流还引用 anthropics/claude-code-action@beta，升级到 v1：把 uses 行里的 @beta 改成 @v1；删掉 mode 输入，因为 Action 现在自动检测模式；把 direct_prompt 换成 prompt；把 max_turns 和 model 这类 CLI 选项移进 claude_args。

常见问题

来源

• Claude Code GitHub Actions（安装、工作流示例、参数、权限、费用、排错，2026 年 10 月 30 日核对）