Claude Code GitHub Actions

• Code Review：在每个拉取请求上自动审查，无需编写工作流
• Claude Code in the cloud：在云基础设施上运行的 Claude Code 会话，而不是在您的机器上
• Claude Agent SDK：GitHub Actions 之外的自定义自动化。Claude Code GitHub Action 建立在 SDK 之上
• GitHub Enterprise Server：带有自托管 GitHub 的 Claude Code

​

设置

• 快速设置：在 Claude Code 中运行 /install-github-app。Claude Code 会为您安装 GitHub App、添加身份验证密钥，并准备好工作流 Pull Request
• 手动设置：自行安装应用、添加密钥，并将工作流文件复制到仓库中。如果您不在本地运行 Claude Code、该命令执行失败，或者您希望完全掌控工作流文件，请使用此方式

​

快速设置

• 如果 Claude Code 已有 API 密钥，则会复用该密钥；如果仓库已设置 ANTHROPIC_API_KEY 密钥，还会询问是否保留现有密钥
• 否则，您可以选择使用 Claude 订阅创建长期令牌，或粘贴 API 密钥

• 再次运行 /install-github-app。当仓库中已有 claude.yml 时，选择 Update workflow file with latest version。Claude Code 会将最新的工作流文件推送到新分支并打开 Pull Request，与首次安装时相同。
• 自行将 审查工作流示例中的 --comment 参数和 claude_args 行添加到已提交的文件中，这样可以保留您对该文件所做的其他修改。

​

手动设置

​

为组织进行设置

• 在组织级别安装一次 Claude GitHub App，选择所有仓库或指定的仓库列表
• 将身份验证密钥存储为组织级别的 Actions 密钥，这样每个仓库就无需单独保存副本
• 将工作流文件添加到每个需要运行 Claude Code GitHub Action 的仓库，或将该作业定义为一个可复用工作流，供各仓库调用

• anthropic_federation_rule_id：联合规则 ID，fdrl_...
• anthropic_organization_id：您的 Anthropic 组织 ID
• anthropic_service_account_id：服务账号 ID，svac_...。可选，因为您在 Console 中创建的联合规则已指向某个服务账号
• anthropic_workspace_id：工作区 ID，wrkspc_...。当联合规则指向单个工作区时为可选

​

卸载

• 工作流文件：从 .github/workflows/ 中删除使用 anthropics/claude-code-action 的工作流。如果您使用的是快速设置，请查找 claude.yml，如果选择了审查工作流，还需查找 claude-code-review.yml。删除工作流后，Claude Code GitHub Action 将不再运行
• 密钥：从仓库中删除 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN 密钥；如果您已跨仓库共享该密钥，还需从组织级别的 Actions 密钥中删除。删除密钥后，其中保存的凭据仍然有效。如需彻底停用 API 密钥，还需在 Claude Console 中删除该密钥
• GitHub App：在仓库或组织设置的 GitHub Apps 下卸载 Claude GitHub App，但前提是您没有将其用于其他 Claude 功能，例如 Code Review 或网页版自动修复

​

GitHub App 权限

​

交互和自动化模式

• 交互模式：当工作流不提供 prompt 输入时，Claude 等待触发短语 @claude（默认），在 issue 或拉取请求评论、拉取请求审查或新打开的 issue 的正文或标题中，然后响应该请求。进度和结果显示为触发 issue 或 PR 上的评论。
• 自动化模式：当工作流提供 prompt 输入时，Claude 运行而不等待提及，仅受谁可以触发运行的检查约束。默认情况下，结果显示在工作流运行日志中而不是评论中。Claude 可以在提示指导它并且它有可以发布的工具时发布到 issue 或拉取请求，如代码审查示例中所示。

​

谁可以触发运行

• 写入访问：在 issue 和拉取请求事件上，触发用户必须对仓库具有写入访问权限。要允许没有写入访问权限的特定用户，请设置 allowed_non_write_users 并传递您自己的 github_token 输入。没有用户创建的事件，例如 schedule 触发器，会跳过此检查。
• 人类参与者：在每个事件上，Claude Code GitHub Action 拒绝机器人参与者，除非您在 allowed_bots 中列出它，这可以防止机器人在循环中触发 Claude。此检查也适用于计划运行，GitHub 将其归因于仓库用户，通常是最后更改工作流 cron 计划的用户。如果该用户是机器人，请在 allowed_bots 中列出它。

​

示例用例

​

响应 @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：Claude Code GitHub Action 的默认 GitHub App 身份验证所需
• actions: read：让 Claude 读取 PR 上的 CI 结果
• actions/checkout：给 Claude 一个本地仓库副本来工作
• if：防止运行器在不提及 @claude 的评论上启动。Claude Code GitHub Action 也在响应之前检查触发短语本身

@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

​

运行 skill

• 对于仓库的 .claude/skills/ 目录中的 skill，在 anthropics/claude-code-action 步骤之前运行 actions/checkout，以便 skill 文件在运行器上可用，然后将 /skill-name 作为 prompt 传递。
• 对于打包在插件中的 skill，使用 plugin_marketplaces 和 plugins 输入安装插件，然后将命名空间的 /plugin-name:skill-name 作为 prompt 传递。plugins 输入采用 plugin-name@marketplace-name，其中市场名称来自市场自己的清单而不是其仓库 URL。

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 在拉取请求上发布其审查，作为它发现的每个问题的内联评论或在它没有发现任何问题时作为一个摘要评论。没有它，Claude 不发布任何内容，您在工作流运行日志中读取发现。
• claude_args：即使 skill 自己的 allowed-tools frontmatter 命名相同的工具，也要保留此行，因为 Claude Code GitHub Action 仅在 claude_args 中的 --allowedTools 命名它时才启动发布内联评论的 MCP 服务器。

​

按计划运行

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 中定义项目标准

​

保护您的凭证

​

管理成本

• GitHub Actions 分钟：Claude Code GitHub Action 在 GitHub 托管的运行器上运行，这会消耗您的 GitHub Actions 分钟。有关定价和分钟限制，请参阅 GitHub 的计费文档。
• API 令牌：每次交互根据提示和响应的长度、任务复杂性和代码库大小消耗令牌。有关当前令牌费率，请参阅 Claude 的定价页面。如果您使用 OAuth 令牌进行身份验证，运行使用您的 Claude 订阅而不是 API 计费。

• 编写特定的 @claude 请求，以便 Claude 需要更少的轮次来完成
• 使用 issue 模板提前提供上下文
• 保持您的 CLAUDE.md 简洁，因为 Claude 在每次运行时都会读取它
• 在 claude_args 中设置 --max-turns 以限制迭代
• 设置工作流级别的超时以避免失控的作业
• 使用 GitHub 的并发控制来限制并行运行

​

使用云提供商

• Amazon Bedrock：use_bedrock: "true"
• Google Cloud 的 Agent Platform：use_vertex: "true"
• Microsoft Foundry：use_foundry: "true"

​

故障排除

​

Claude 不响应 @claude 命令

• 验证 GitHub App 是否安装在仓库上
• 检查工作流是否为仓库启用
• 确保您的 API 密钥或 OAuth 令牌在仓库密钥中设置
• 确认评论包含 @claude 作为完整单词，而不是 /claude 或 @claude-bot
• 确认评论用户对仓库具有写入访问权限。有关例外，请参阅谁可以触发运行

​

CI 不在 Claude 的提交上运行

• GitHub 不会在使用默认 GITHUB_TOKEN 进行的提交上触发工作流。如果您将 github_token: ${{ secrets.GITHUB_TOKEN }} 传递给 Claude Code GitHub Action，请删除它以便它作为 Claude GitHub App 进行身份验证，或改为传递自定义应用令牌
• 检查您的 CI 工作流的触发器是否包括 Claude 的推送产生的事件，例如 push 或 pull_request

​

身份验证错误

• 通过在本地使用 claude 测试 API 密钥或 OAuth 令牌来确认它有效，然后再调试工作流
• 对于 Bedrock、Agent Platform 和 Foundry，请参阅云提供商页面的故障排除部分

​

高级配置

​

Action 参数

​

传递 CLI 参数

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

• --max-turns：限制对话轮数
• --model：要使用的模型，例如 claude-sonnet-5。没有此参数，Claude Code GitHub Action 使用 Claude Code 默认模型
• --mcp-config：MCP 配置的路径
• --allowedTools：允许的工具的逗号分隔列表。--allowed-tools 别名也可以使用
• --debug：启用调试输出

​

从 beta 升级

1. 在 uses 行中将 @beta 更改为 @v1
2. 删除 mode 输入，因为 Claude Code GitHub Action 现在自动检测模式
3. 将 direct_prompt 替换为 prompt
4. 将 CLI 选项（如 max_turns 和 model）移到 claude_args 中。custom_instructions 没有同名标志，变成 --append-system-prompt

​

接下来

• 将 Claude Code GitHub Actions 与云提供商一起使用：通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 路由推理
• 配置参考：action 输入的完整列表
• Examples 目录：更多场景的现成工作流
• Code Review：无需维护工作流文件的自动拉取请求审查