Claude Code GitHub Actions
了解如何使用 Claude Code GitHub Actions 将 Claude Code 集成到您的开发工作流程中
Claude Code GitHub Actions 为您的 GitHub 工作流程带来 AI 驱动的自动化。只需在任何 PR 或 issue 中简单地提及 @claude
,Claude 就可以分析您的代码、创建拉取请求、实现功能和修复错误 - 所有这些都遵循您项目的标准。
Claude Code GitHub Actions 目前处于测试阶段。随着我们完善体验,功能和特性可能会发生变化。
Claude Code GitHub Actions 基于 Claude Code SDK 构建,该 SDK 支持将 Claude Code 程序化集成到您的应用程序中。您可以使用 SDK 构建超越 GitHub Actions 的自定义自动化工作流程。
为什么使用 Claude Code GitHub Actions?
- 即时 PR 创建:描述您的需求,Claude 会创建包含所有必要更改的完整 PR
- 自动化代码实现:通过单个命令将 issue 转换为可工作的代码
- 遵循您的标准:Claude 尊重您的
CLAUDE.md
指南和现有代码模式 - 简单设置:使用我们的安装程序和 API 密钥在几分钟内开始使用
- 默认安全:您的代码保留在 Github 的运行器上
Claude 能做什么?
Claude Code 提供强大的 GitHub Actions,改变您处理代码的方式:
Claude Code Action
此 GitHub Action 允许您在 GitHub Actions 工作流程中运行 Claude Code。您可以使用它在 Claude Code 之上构建任何自定义工作流程。
Claude Code Action (Base)
使用 Claude 构建自定义 GitHub 工作流程的基础。这个可扩展的框架为您提供对 Claude 功能的完全访问权限,用于创建定制的自动化。
设置
快速设置
设置此操作的最简单方法是通过终端中的 Claude Code。只需打开 claude 并运行 /install-github-app
。
此命令将指导您完成设置 GitHub 应用程序和所需密钥的过程。
- 您必须是仓库管理员才能安装 GitHub 应用程序和添加密钥
- 此快速启动方法仅适用于直接 Anthropic API 用户。如果您使用 AWS Bedrock 或 Google Vertex AI,请参阅与 AWS Bedrock 和 Google Vertex AI 一起使用部分。
手动设置
如果 /install-github-app
命令失败或您更喜欢手动设置,请按照以下手动设置说明操作:
- 将 Claude GitHub 应用程序安装到您的仓库:https://github.com/apps/claude
- 将 ANTHROPIC_API_KEY 添加到您的仓库密钥中(了解如何在 GitHub Actions 中使用密钥)
- 复制工作流程文件从 examples/claude.yml 到您仓库的
.github/workflows/
完成快速启动或手动设置后,通过在 issue 或 PR 评论中标记 @claude
来测试操作!
示例用例
Claude Code GitHub Actions 可以帮助您完成各种任务。有关完整的工作示例,请参阅示例目录。
将 issue 转换为 PR
在 issue 评论中:
Claude 将分析 issue,编写代码,并创建 PR 供审查。
获取实现帮助
在 PR 评论中:
Claude 将分析您的代码并提供具体的实现指导。
快速修复错误
在 issue 中:
Claude 将定位错误,实现修复,并创建 PR。
最佳实践
CLAUDE.md 配置
在您的仓库根目录中创建一个 CLAUDE.md
文件来定义代码风格指南、审查标准、项目特定规则和首选模式。此文件指导 Claude 理解您的项目标准。
安全考虑
永远不要直接将 API 密钥提交到您的仓库!
始终使用 GitHub 密钥来存储 API 密钥:
- 将您的 API 密钥添加为名为
ANTHROPIC_API_KEY
的仓库密钥 - 在工作流程中引用它:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
- 将操作权限限制为仅必需的权限
- 在合并之前审查 Claude 的建议
始终使用 GitHub 密钥(例如,${{ secrets.ANTHROPIC_API_KEY }}
)而不是在工作流程文件中直接硬编码 API 密钥。
优化性能
使用 issue 模板提供上下文,保持您的 CLAUDE.md
简洁和专注,并为您的工作流程配置适当的超时。
CI 成本
使用 Claude Code GitHub Actions 时,请注意相关成本:
GitHub Actions 成本:
- Claude Code 在 GitHub 托管的运行器上运行,这会消耗您的 GitHub Actions 分钟数
- 有关详细定价和分钟数限制,请参阅 GitHub 的计费文档
API 成本:
- 每次 Claude 交互都会根据提示和响应的长度消耗 API 令牌
- 令牌使用量因任务复杂性和代码库大小而异
- 有关当前令牌费率,请参阅 Claude 的定价页面
成本优化提示:
- 使用特定的
@claude
命令来减少不必要的 API 调用 - 配置适当的
max_turns
限制以防止过度迭代 - 设置合理的
timeout_minutes
以避免失控的工作流程 - 考虑使用 GitHub 的并发控制来限制并行运行
配置示例
对于不同用例的即用型工作流程配置,包括:
- issue 和 PR 评论的基本工作流程设置
- 拉取请求的自动化代码审查
- 特定需求的自定义实现
访问 Claude Code Action 仓库中的示例目录。
示例仓库包含完整的、经过测试的工作流程,您可以直接复制到您的 .github/workflows/
目录中。
与 AWS Bedrock 和 Google Vertex AI 一起使用
对于企业环境,您可以将 Claude Code GitHub Actions 与您自己的云基础设施一起使用。这种方法让您控制数据驻留和计费,同时保持相同的功能。
先决条件
在使用云提供商设置 Claude Code GitHub Actions 之前,您需要:
对于 Google Cloud Vertex AI:
- 启用了 Vertex AI 的 Google Cloud 项目
- 为 GitHub Actions 配置的工作负载身份联合
- 具有所需权限的服务帐户
- GitHub 应用程序(推荐)或使用默认的 GITHUB_TOKEN
对于 AWS Bedrock:
- 启用了 Amazon Bedrock 的 AWS 帐户
- 在 AWS 中配置的 GitHub OIDC 身份提供者
- 具有 Bedrock 权限的 IAM 角色
- GitHub 应用程序(推荐)或使用默认的 GITHUB_TOKEN
创建自定义 GitHub 应用程序(推荐用于第三方提供商)
为了在使用 Vertex AI 或 Bedrock 等第三方提供商时获得最佳控制和安全性,我们建议创建您自己的 GitHub 应用程序:
- 转到 https://github.com/settings/apps/new
- 填写基本信息:
- GitHub 应用程序名称:选择一个唯一的名称(例如,“YourOrg Claude Assistant”)
- 主页 URL:您组织的网站或仓库 URL
- 配置应用程序设置:
- Webhooks:取消选中”Active”(此集成不需要)
- 设置所需权限:
- 仓库权限:
- Contents:读取和写入
- Issues:读取和写入
- Pull requests:读取和写入
- 仓库权限:
- 点击”创建 GitHub 应用程序”
- 创建后,点击”生成私钥”并保存下载的
.pem
文件 - 从应用程序设置页面记下您的应用程序 ID
- 将应用程序安装到您的仓库:
- 从您应用程序的设置页面,点击左侧边栏中的”安装应用程序”
- 选择您的帐户或组织
- 选择”仅选择仓库”并选择特定仓库
- 点击”安装”
- 将私钥作为密钥添加到您的仓库:
- 转到您仓库的设置 → 密钥和变量 → Actions
- 创建一个名为
APP_PRIVATE_KEY
的新密钥,内容为.pem
文件的内容
- 将应用程序 ID 作为密钥添加:
- 创建一个名为
APP_ID
的新密钥,值为您的 GitHub 应用程序的 ID
此应用程序将与 actions/create-github-app-token 操作一起使用,在您的工作流程中生成身份验证令牌。
Anthropic API 的替代方案或如果您不想设置自己的 Github 应用程序:使用官方 Anthropic 应用程序:
- 从以下位置安装:https://github.com/apps/claude
- 身份验证无需额外配置
配置云提供商身份验证
选择您的云提供商并设置安全身份验证:
添加所需密钥
将以下密钥添加到您的仓库(设置 → 密钥和变量 → Actions):
对于 Anthropic API(直接):
-
用于 API 身份验证:
ANTHROPIC_API_KEY
:来自 console.anthropic.com 的 Anthropic API 密钥
-
用于 GitHub 应用程序(如果使用您自己的应用程序):
APP_ID
:您的 GitHub 应用程序的 IDAPP_PRIVATE_KEY
:私钥(.pem)内容
对于 Google Cloud Vertex AI
-
用于 GCP 身份验证:
GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT
-
用于 GitHub 应用程序(如果使用您自己的应用程序):
APP_ID
:您的 GitHub 应用程序的 IDAPP_PRIVATE_KEY
:私钥(.pem)内容
对于 AWS Bedrock
-
用于 AWS 身份验证:
AWS_ROLE_TO_ASSUME
-
用于 GitHub 应用程序(如果使用您自己的应用程序):
APP_ID
:您的 GitHub 应用程序的 IDAPP_PRIVATE_KEY
:私钥(.pem)内容
创建工作流程文件
创建与您的云提供商集成的 GitHub Actions 工作流程文件。以下示例显示了 AWS Bedrock 和 Google Vertex AI 的完整配置:
故障排除
Claude 不响应 @claude 命令
验证 GitHub 应用程序是否正确安装,检查工作流程是否已启用,确保 API 密钥已在仓库密钥中设置,并确认评论包含 @claude
(不是 /claude
)。
CI 不在 Claude 的提交上运行
确保您使用的是 GitHub 应用程序或自定义应用程序(不是 Actions 用户),检查工作流程触发器是否包含必要的事件,并验证应用程序权限是否包含 CI 触发器。
身份验证错误
确认 API 密钥有效且具有足够的权限。对于 Bedrock/Vertex,检查凭据配置并确保密钥在工作流程中正确命名。
高级配置
操作参数
Claude Code Action 支持以下关键参数:
参数 | 描述 | 必需 |
---|---|---|
prompt | 发送给 Claude 的提示 | 是* |
prompt_file | 包含提示的文件路径 | 是* |
anthropic_api_key | Anthropic API 密钥 | 是** |
max_turns | 最大对话轮数 | 否 |
timeout_minutes | 执行超时 | 否 |
*需要 prompt
或 prompt_file
之一
**直接 Anthropic API 需要,Bedrock/Vertex 不需要
替代集成方法
虽然 /install-github-app
命令是推荐的方法,但您也可以:
- 自定义 GitHub 应用程序:对于需要品牌用户名或自定义身份验证流程的组织。创建您自己的具有所需权限(内容、issue、拉取请求)的 GitHub 应用程序,并使用 actions/create-github-app-token 操作在您的工作流程中生成令牌。
- 手动 GitHub Actions:直接工作流程配置以获得最大灵活性
- MCP 配置:模型上下文协议服务器的动态加载
有关详细文档,请参阅 Claude Code Action 仓库。
自定义 Claude 的行为
您可以通过两种方式配置 Claude 的行为:
- CLAUDE.md:在仓库根目录的
CLAUDE.md
文件中定义编码标准、审查标准和项目特定规则。Claude 在创建 PR 和响应请求时将遵循这些指南。查看我们的内存文档了解更多详情。 - 自定义提示:在工作流程文件中使用
prompt
参数提供特定于工作流程的说明。这允许您为不同的工作流程或任务自定义 Claude 的行为。
Claude 在创建 PR 和响应请求时将遵循这些指南。