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

开始之前

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

这个 action 建立在 Agent SDK 之上，claude_args 接受的参数和无头运行那一课里的 claude -p 一样。安全方面的细节来自仓库自己的文档。以上内容都读于 2026 年 11 月 4 日，GitHub Actions 页面在本课更新时又核对过一遍。

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

安装它，发出第一条 @claude

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

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，添加密钥，把工作流复制进 .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 里写的工具。页面里的这个代码评审工作流只授予一个行内评论工具，并让令牌保持只读。

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

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 带着基础仓库的密钥运行。这让检出成了最危险的一步，而下面是安全页面在你需要拉取请求文件时给出的写法。

# 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 的计费页面和 Claude 的定价页面，没有印出任何数字。

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

- 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 上一串技巧的第 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 每次运行都会读这个文件。

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 构建智能体，把同样的循环当作一个库来用。

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

常见问题

资料来源

1. Claude Code docs: Claude Code GitHub Actions (2026年11月5日 查阅)https://code.claude.com/docs/en/github-actions
2. claude-code-action docs: Security (2026年11月4日 查阅)https://github.com/anthropics/claude-code-action/blob/main/docs/security.md
3. claude-code-action docs: Usage (2026年11月4日 查阅)https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
4. claude-code-action docs: FAQ (2026年11月4日 查阅)https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md
5. claude-code-action docs: Setup guide (2026年11月4日 查阅)https://github.com/anthropics/claude-code-action/blob/main/docs/setup.md
6. anthropics/claude-code-action on GitHub (2026年11月5日 查阅)https://github.com/anthropics/claude-code-action
7. claude-code-action release v1.0.268 on GitHub (2026年11月5日 查阅)https://github.com/anthropics/claude-code-action/releases/tag/v1.0.268
8. Boris Cherny on X: tag @claude on PRs to update CLAUDE.md (2026年11月5日 查阅)https://x.com/bcherny/status/2007179842928947333