# Claude Code GitHub Actions：设置 @claude、工作流、密钥和限制

> Claude Code GitHub Action 在你仓库的工作流里运行 Claude Code。在 Claude Code 里运行 `/install-github-app`，它会安装 GitHub App、保存密钥，并开一个带工作流的拉取请求。合并之后，在 issue 或拉取请求的评论里提到 `@claude` 就行。给工作流加上 `prompt`，它就会在任何 GitHub 事件上运行，所以要限定它的权限、工具和回合数。

Mindket 编辑部 · 发布于 2026-11-04 · 更新于 2026-11-05 · https://mindket.com/cn/learn/claude-code-advanced/claude-code-github-actions

## 要点

- `/install-github-app` 会安装应用，把 `ANTHROPIC_API_KEY` 或 `CLAUDE_CODE_OAUTH_TOKEN` 存成密钥，并开一个带工作流的拉取请求。它需要管理员权限，仓库要在 github.com 上。
- 没有 `prompt` 输入就是交互模式：Claude 等着 `@claude`。有 `prompt` 输入就是自动化模式，在你选定的任何事件上运行。
- 只有拥有写权限的用户才能触发运行，机器人除非列进 `allowed_bots` 否则会被拒绝。永远不要把不可信的拉取请求头部检出到工作区根目录。
- 费用有两部分：Actions 分钟数和 API token。用 `claude_args` 里的 `--max-turns`、工作流超时和并发控制来限制。

## 开始之前

你需要一个自己有管理员权限的 github.com 仓库、本机的 Claude Code，以及用 `gh auth login` 登录好的 [GitHub CLI](https://cli.github.com)。GitLab 或 Bitbucket 的远程仓库用不了快速安装。好几款 Anthropic 产品都叫 Claude Code，这一课只讲 [Anthropic 的 GitHub Actions 页面](https://code.claude.com/docs/en/github-actions)里的 `claude-code-action` 工作流集成。

这个 action 建立在 Agent SDK 之上，`claude_args` 接受的参数和[无头运行那一课](https://mindket.com/cn/learn/claude-code-advanced/claude-code-headless)里的 `claude -p` 一样。安全方面的细节来自[仓库自己的文档](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md)。以上内容都读于 2026 年 11 月 4 日，GitHub Actions 页面在本课更新时又核对过一遍。

这个 action 发版很勤，所以固定写 `@v1`，让它自己往前走。下面几个数字说明它用得有多广，以及本课核对时它有多新。

**GitHub 上的 claude-code-action 仓库**

- **9.8k** anthropics/claude-code-action 获得的星标 (来源：[anthropics/claude-code-action on GitHub](https://github.com/anthropics/claude-code-action), 2026-11-05 查阅)
- **2.2k** 这个仓库的 fork 数 (来源：[anthropics/claude-code-action on GitHub](https://github.com/anthropics/claude-code-action), 2026-11-05 查阅)
- **v1.0.268** 最新的版本，发布于本课核对的前一天 (来源：[claude-code-action release v1.0.268 on GitHub](https://github.com/anthropics/claude-code-action/releases/tag/v1.0.268), 2026-11-05 查阅)

## 安装它，发出第一条 @claude

快速安装会装上 Claude GitHub App，并把你的凭据存成仓库密钥，然后用一个拉取请求把工作流提交给你。这份工作流就是下面这个，手动安装时也是从仓库的 examples 文件夹里复制它。

````yaml
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 }}
````

1. 在仓库里打开 `claude`，运行 `/install-github-app`。Claude Code 先安装应用。如果它已经有 API 密钥就直接复用，否则你要在“用 Claude 订阅生成的长期令牌”和“粘贴一个 API 密钥”之间二选一。
2. Claude Code 把凭据存成密钥：API 密钥叫 `ANTHROPIC_API_KEY`，订阅令牌叫 `CLAUDE_CODE_OAUTH_TOKEN`。接着它推送一个分支，里面是你选的工作流文件，已经指向那个密钥，并打开 GitHub，一个拉取请求已经备好，等你创建。
3. 创建并合并这个拉取请求。然后在某个 issue 下评论一个请求，比如 `@claude how should I implement user authentication for this endpoint?`。Claude 会在同一个 issue 下用一条评论回答，并随着工作进展更新它。
4. 本机没有 Claude Code，或者命令失败时，就手动安装。装上 [Claude GitHub App](https://github.com/apps/claude)，添加密钥，把工作流复制进 `.github/workflows/`。用订阅令牌的话，在本机运行 `claude setup-token`，再把 `anthropic_api_key` 那一行改成 `claude_code_oauth_token`。

## 工作流的每一部分有什么用

Anthropic 的页面点出了那些不是样板的行。大多数麻烦都出在其中某一行不见了。

- `id-token: write` 是默认的 GitHub App 认证所必需的。缺了它就会出现 OIDC 错误，而且即使你为工作负载身份联合传入了自己的令牌，这个权限也还是要保留。
- `actions: read` 让 Claude 能读拉取请求上的 CI 结果。FAQ 还建议在 action 这一步上加 `additional_permissions: actions: read`。
- `actions/checkout` 给 Claude 一份仓库的本地副本。Claude 做浅克隆，拉取请求是 20 个提交，新分支是 1 个，所以需要完整历史时要自己设置检出深度。
- `if` 让没有 `@claude` 的评论不会启动 runner。action 在响应之前，自己也会检查触发短语。
- contents、issues 和 pull requests 给予写权限，因为它们正是这个 action 依赖的三项应用权限：Claude 修改文件、回应 issue 并推送改动。

## 两种模式，以及谁能触发运行

action 从工作流里自动判断模式，没有 `mode` 输入可设。没有 `prompt` 时它以交互方式运行，等着触发短语，默认是 `@claude`，出现在评论、评审，或者新 issue 的标题和正文里。有 `prompt` 时它以自动化模式，在你的 `on:` 块里写的任何事件上运行，结果会进运行日志，除非提示词让 Claude 把它发出来。

纯文本的提示词没有 shell 或 GitHub API 的访问权，直到你用 `claude_args` 里的 `--allowedTools`，或者 `settings` 输入里的 `permissions.allow` 规则授予工具。技能则带上它 `allowed-tools` frontmatter 里写的工具。页面里的这个代码评审工作流只授予一个行内评论工具，并让令牌保持只读。

````yaml
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"'
````

| 触发者 | 结果 |
| --- | --- |
| 有写权限的用户 | 运行启动 |
| 没有写权限的用户 | 被拒绝。`allowed_non_write_users` 可以取消这项检查，而且只有配合你自己的 `github_token` 才有效 |
| 机器人或 GitHub App | 除非列进 `allowed_bots`，否则被拒绝。列入名单的机器人不做权限检查 |
| 定时运行 | 不做写权限检查。GitHub 把它记在最后修改 cron 那一行的用户名下，那里如果是机器人，就必须列进 `allowed_bots` |
| 由 fork 拉取请求启动的 `workflow_run` | action 还会检查发起上游运行的那个人，如果他没有写权限就会停下。绕过它的办法是 `allowed_non_write_users` 配合你自己的 `github_token` |

## Claude 能碰到什么，以及检出这个陷阱

action 在你的 runner 上运行，用的是 Claude GitHub App 发的短期令牌。这个令牌的范围限定在这次运行所在的那一个仓库。安装应用就等于授予它的整套权限，GitHub 不允许只接受一部分。如果你的组织只想要 contents、issues 和 pull requests，文档介绍了只含这三项的自定义 GitHub App。仓库安全页面列出的应用权限比文档表格里的少，所以请以安装界面为准。

默认情况下 Claude 不会自己开拉取请求。按安全页面的说法，它把改动提交到一个新分支，并贴出创建页面的链接，由人来决定，分支保护依然挡在流程里。FAQ 说 Claude 从不合并、变基或强制推送，而且这写在它的系统提示词里，所以即使你放行了 git 工具，这一点依然成立。

在拉取请求上，action 先从基础分支恢复一份固定的 Claude 文件清单：`.claude/`、`.mcp.json`、`.claude.json`、`.gitmodules`、`.ripgreprc`、`CLAUDE.md`、`CLAUDE.local.md` 和 `.husky/`。拉取请求自带的那些副本留在 `.claude-pr/` 下，仅供参考。其余一切仍停在头部提交上，所以运行 `npm run format` 的 hook 依然会经过这个拉取请求的 `package.json`。hook 命令要写成自包含的。

`pull_request_target` 和 `workflow_run` 带着基础仓库的密钥运行。这让检出成了最危险的一步，而下面是安全页面在你需要拉取请求文件时给出的写法。

> 不要在运行这个 action 之前，把不可信的 ref 检出到工作区根目录。
>
> Anthropic, claude-code-action 仓库文档（此处为中文译文）, [claude-code-action 文档：Security](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md) (2026-11-04 查阅)

````yaml
# If you need the PR's files locally, check out the base ref at the workspace
# root (this action expects a git repo there), then check out the head ref into
# a subdirectory and pass it via --add-dir.
- uses: actions/checkout@v6 # no ref input: base branch at workspace root
- uses: actions/checkout@v6
  with:
    # For workflow_run use: ${{ github.event.workflow_run.head_sha }}
    ref: ${{ github.event.pull_request.head.sha }}
    path: pr-head
- uses: anthropics/claude-code-action@v1
  with:
    claude_args: "--add-dir pr-head"
````

## 不可信的输入，以及会放宽它的设置

- 隐藏的指令可以藏在 HTML 注释、不可见字符和隐藏属性里。action 会剥掉 HTML 注释、不可见字符、图片替代文字、隐藏属性和实体字符，文档也说可能出现新的绕过办法。在对外部人员的 issue 提到 Claude 之前，先读一遍原始文本。在公开仓库里，`include_comments_by_actor` 限定哪些人的评论能传给 Claude，某个用户同时在两个名单里时，排除优先。
- 在公开仓库里设 `allowed_bots: '*'`，会让任何 GitHub App 都能带着它自己控制的提示词调用这个 action。请优先用具名名单。
- `allowed_non_write_users` 被标为有风险。它只配合 `github_token` 使用，这个令牌应该是 `secrets.GITHUB_TOKEN`，绝不能是个人访问令牌，文档还建议把工具限制到最少。Claude 会尽力从子进程环境里清除密钥，`CLAUDE_CODE_SCRIPT_CAPS` 则限制具名脚本的调用次数。
- `show_full_output` 默认关闭，因为它会打印每一条工具结果，包括 `env` 和文件读取，而公开仓库里这些日志对所有人可见。Actions 调试模式一开，它也会自动打开。
- action 里的 Bash 工具默认是关的。请在 `--allowedTools` 里列出命令，比如 `Bash(npm:*)`。GitHub 和文件操作这两个 MCP 服务器会自动启动，它们的工具仍然需要 `--allowedTools`。
- 想让静态密钥不进仓库，就用工作负载身份联合。action 通过 Console 服务账号，把工作流的 OIDC 令牌换成 Claude API 的访问权，用到 `anthropic_federation_rule_id` 和 `anthropic_organization_id`。

## 费用，以及怎样让失控的任务停下来

每次运行都会在你的 runner 上消耗 GitHub Actions 分钟数，每次交互还会消耗 API token。用 OAuth 令牌时，token 从你的 Claude 订阅里扣，不走 API 计费。价格会变，所以文档只指向 [GitHub 的计费页面](https://github.com/settings/billing/summary)和 [Claude 的定价页面](https://claude.com/pricing)，没有印出任何数字。

`claude_args` 接受任何命令行参数，v1 版 action 就是这样带上 `--max-turns` 和系统提示词的追加内容。

````yaml
- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --max-turns 10
      --append-system-prompt "Focus on security"
````

- 写具体的 `@claude` 请求，并用 issue 模板，让 Claude 需要的回合更少。
- 让 CLAUDE.md 保持简短，因为 Claude 每次运行都会读它。里面该放什么，见 CLAUDE.md 指南。
- 在 `claude_args` 里设 `--max-turns`，再设工作流级别的超时和 GitHub 的并发控制，限制并行的运行。

## Boris Cherny 的评审习惯：提到 @claude，让它更新 CLAUDE.md

Boris Cherny 是 Claude Code 的作者，他在 [X 上](https://x.com/bcherny/status/2007179842928947333)一串技巧的第 5 条里讲了一个评审习惯。

做代码评审时，他常在同事的拉取请求上提到 Claude，请它把某条内容加进 CLAUDE.md，作为这个拉取请求的一部分。他的团队用 GitHub Action 来做这件事，他说这是他们版本的 Compounding Engineering，这个说法来自 Dan Shipper。

他帖子里写的命令是 `/install-github-action`。Anthropic 文档里的命令是 `/install-github-app`，也就是本课用的那个。

想照着做，就保留上面那份提及工作流，并保留 `contents: write` 和 `pull-requests: write`，让 Claude 能把对 CLAUDE.md 的修改提交到同一个拉取请求里。评审时评论 `@claude add a line to CLAUDE.md about`，后面接你刚发现的问题。规则跟着教会它的那次改动一起落地。每一行都写短一点，因为 Claude 每次运行都会读这个文件。

> 我们用 Claude Code 的 GitHub action（/install-github-action）来做这件事。
>
> Boris Cherny, Claude Code 的作者，就职于 Anthropic，引文为译文, [X](https://x.com/bcherny/status/2007179842928947333) (2026-11-05 查阅)

[![Boris Cherny（@bcherny）2026 年 1 月 2 日在 X 上发的第 5 条技巧：做代码评审时，他常在同事的 PR 上提到 @.claude，把某条内容加进 CLAUDE.md，作为这个 PR 的一部分，用的是 Claude Code 的 GitHub action。](https://mindket.com/blog/shots/x-bcherny-tag-claude-on-prs.webp?v=9fe081cc1404)](https://x.com/bcherny/status/2007179842928947333)

Boris Cherny 在 X 上，2026 年 1 月 2 日

> X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日，时间为 UTC。点击截图可到 X 上打开原帖。

## 常见错误

- 在另一个工作流里提到 `@claude`。`github-actions` 用户不能触发后续工作流，这是为了防止死循环，所以这条评论要用你自己的用户或应用的令牌来发。
- 传入 `github_token: secrets.GITHUB_TOKEN`，然后纳闷为什么 CI 跳过了 Claude 的提交。GitHub 不会为用这个令牌做出的提交运行工作流。去掉这个输入，让 action 以 Claude GitHub App 的身份认证，同时要知道 `allowed_non_write_users` 需要你自己的令牌。
- 评论里的触发短语不是一个完整的词。`/claude` 和 `@claude-bot` 什么也触发不了，除非你修改 `trigger_phrase`。
- 工作流还停在 `@beta`。把它改成 `@v1`，去掉 `mode` 输入，把 `direct_prompt` 改名为 `prompt`，把 `max_turns` 和 `model` 挪进 `claude_args`。
- 还没验证凭据就开始调试工作流。先在本机用 `claude` 测一下 API 密钥或 OAuth 令牌。

## 动手试试

- 在一个练手仓库里运行 `/install-github-app`，合并拉取请求，然后评论 `@claude`，问一个关于某个文件的问题。看那一条评论随着运行进展被更新。
- 先评论 `/claude`，再评论 `@claude-bot`，确认都不会启动运行。改掉 `trigger_phrase` 后再试一次。
- 复制那个评审工作流，去掉 `id-token: write`，在运行日志里读一读报错，然后把它加回去。
- 给工作流加上 `claude_args: "--max-turns 3"`，再给 Claude 一个需要更多回合的任务。比较有上限和没有上限时的运行。

## 下一课：用 Agent SDK 构建你自己的智能体

Anthropic 把 Claude Agent SDK 指给 GitHub Actions 之外的自动化，这个 action 本身也跑在它之上。最后一课[用 Claude Agent SDK 构建智能体](https://mindket.com/cn/learn/claude-code-advanced/claude-agent-sdk)，把同样的循环当作一个库来用。

上面的评审工作流已经通过 `plugins` 和 `plugin_marketplaces` 两个输入安装了一个插件。插件里能放什么，见插件那篇文章。

## 自测一下

1. 一个工作流步骤使用 anthropics/claude-code-action@v1，没有 prompt 输入。这个 action 会怎么做？

   A. 在每个事件上都用默认的评审提示词运行
   B. 等待触发短语，默认是评论或新 issue 里的 @claude
   C. 失败，因为 prompt 输入是必填的

   答案：B。 没有 prompt 时 action 以交互模式运行，只有当有人用了触发短语才响应。

2. 默认的 GitHub App 认证要求任务授予哪项权限？

   A. id-token: write
   B. packages: write
   C. security-events: write

   答案：A。 默认认证会获取 GitHub OIDC 令牌，所以任务必须授予 id-token: write，否则运行会出现 OIDC 错误。

3. Claude 推送了提交，但你的 CI 工作流没有在上面启动。最可能的原因是什么？

   A. GitHub 会拦截以 claude/ 开头的分支
   B. 缺少 id-token 权限
   C. 这一步把默认的 GITHUB_TOKEN 当作 github_token 传入，而 GitHub 不会为用它做出的提交运行工作流

   答案：C。 GitHub 不会在用默认令牌做出的提交上触发工作流，所以去掉这个输入，让 action 以 Claude GitHub App 的身份认证。

4. pull_request_target 工作流必须把拉取请求的文件交给 Claude。安全页面建议怎么做？

   A. 把拉取请求的头部检出到工作区根目录，让 Claude 先看到它
   B. 把拉取请求的文件贴进提示词
   C. 关掉基础分支的恢复
   D. 把基础 ref 检出到根目录，把头部检出到子目录，再用 --add-dir 传入

   答案：D。 这些事件带着基础仓库的密钥运行，所以在 action 运行之前，不可信的 ref 不能落到工作区根目录。

## 常见问题

### 能通过指派 issue 或打标签来启动运行吗？

能。在 `on:` 块的 `issues` 事件里加上 `assigned` 和 `labeled`，再在 action 这一步把 `assignee_trigger` 设为被指派者的用户名，或把 `label_trigger` 设为标签名。它们和 `trigger_phrase` 并列，后者默认是 `@claude`。

### 这个 action 需要 API 密钥吗？

需要一种凭据。用 [Claude Console](https://platform.claude.com/settings/keys) 的 `ANTHROPIC_API_KEY`，或者订阅套餐下用 `claude setup-token` 得到的 `CLAUDE_CODE_OAUTH_TOKEN`。要在整个组织里共用一个密钥，请用 API 密钥，因为 OAuth 令牌绑定的是运行那条命令的人。工作负载身份联合可以避免静态密钥。

### 为什么 @claude 没有响应？

检查应用是否已安装、工作流是否已启用、密钥是否存在、评论里是否有作为完整单词的 `@claude`，以及评论者有没有写权限。缺少 `id-token: write` 权限也会让运行失败。

### Claude 能创建并合并拉取请求吗？

默认情况下它创建一个分支，并贴出预填好的拉取请求页面的链接，由人来创建拉取请求。它不会合并、变基或强制推送，也只推送到它自己的分支，或它被调用时所在的拉取请求分支。

### 在公开仓库上运行安全吗？

做好防范可以。评论的人需要有写权限，机器人默认被拦下，文档还要求把工作流的权限收到最小。剩下的风险是通过不可信文本发起的提示词注入，清理手段不能完全挡住它，文档提醒可能出现新的绕过办法。

### 一次运行要花多少钱？

每次运行会消耗 GitHub Actions 分钟数，用 API 密钥时还有 token，数量取决于提示词长度、任务和代码库大小。用 OAuth 令牌时则用你的订阅。用 `--max-turns` 限制回合，再设超时和并发上限。

### 它能配合 GitLab、Bedrock 或 Vertex 使用吗？

`/install-github-app` 只适用于 github.com 的仓库，GitLab 有自己的页面，叫 Claude Code GitLab CI/CD。要用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry，把 `use_bedrock`、`use_vertex` 或 `use_foundry` 设为 `"true"`，并通过 OIDC 认证。

## 资料来源

- [Claude Code docs: Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions) (2026-11-05 查阅)
- [claude-code-action docs: Security](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md) (2026-11-04 查阅)
- [claude-code-action docs: Usage](https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md) (2026-11-04 查阅)
- [claude-code-action docs: FAQ](https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md) (2026-11-04 查阅)
- [claude-code-action docs: Setup guide](https://github.com/anthropics/claude-code-action/blob/main/docs/setup.md) (2026-11-04 查阅)
- [anthropics/claude-code-action on GitHub](https://github.com/anthropics/claude-code-action) (2026-11-05 查阅)
- [claude-code-action release v1.0.268 on GitHub](https://github.com/anthropics/claude-code-action/releases/tag/v1.0.268) (2026-11-05 查阅)
- [Boris Cherny on X: tag @claude on PRs to update CLAUDE.md](https://x.com/bcherny/status/2007179842928947333) (2026-11-05 查阅)

[浏览工具包](https://mindket.com/cn/kits)