介绍如何将 Claude Code 集成到 GitHub Actions 工作流中。通过安装 GitHub App 并配置 API Key 密钥，开发者可以在 PR 或 Issue 中通过 @claude 触发自动化任务。支持 Sonnet 和 Opus 模型，提供快速设置与手动设置两种方案。内容涵盖从 Beta 版升级到 v1.0 的变更点、基本工作流示例、代码评审及自定义自动化用例。同时包含最佳实践建议，如使用 CLAUDE.md 定义规范、安全存储密钥、优化性能与成本控制。适用于希望利用 AI 提升开发效率的团队。
beaabea1.5K 浏览
Claude Code 集成至 GitHub Actions 工作流指南
Learn about integrating Claude Code into your development workflow with Claude Code GitHub Actions.
了解如何使用 Claude Code GitHub Actions 将 Claude Code 集成到您的开发工作流程中。
Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow. With a simple @claude mention in any PR or issue, Claude can analyze your code, create pull requests, implement features, and fix bugs - all while following your project's standards.
Claude Code GitHub Actions 为您的 GitHub 工作流程带来了 AI 驱动的自动化。在任何 PR 或 Issue 中简单提及 @claude，Claude 就能分析您的代码、创建拉取请求、实现功能并修复错误——所有操作都遵循你的项目标准。
Claude Code GitHub Actions is built on top of the Claude Code SDK, which enables programmatic integration of Claude Code into your applications. You can use the SDK to build custom automation workflows beyond GitHub Actions.
Claude Code GitHub Actions 基于 Claude Code SDK 构建，该 SDK 支持将 Claude Code 程序化集成到您的应用程序中。您可以使用 SDK 构建超出 GitHub Actions 的自定义自动化工作流程。
Claude Code GitHub Actions default to Sonnet. To use Opus 4.5, configure the model parameter to use claude-opus-4-5-20251101.
Claude Code GitHub Actions 默认使用 Sonnet。要使用 Opus 4.5，请配置模型参数以使用 claude-opus-4-5-20251101。
一、Why use Claude Code GitHub Actions?
为什么使用 Claude Code GitHub Actions？
Instant PR creation: Describe what you need, and Claude creates a complete PR with all necessary changes
即时创建 PR：描述你的需求，Claude 会创建一个包含所有必要更改的完整 PR
Automated code implementation: Turn issues into working code with a single command
自动化代码实现：通过一个命令将 Issues 转化为可运行的代码
Follows your standards: Claude respects your CLAUDE.md guidelines and existing code patterns
遵循你的标准：Claude 尊重你的 CLAUDE.md 指南和现有代码模式
Simple setup: Get started in minutes with our installer and API key
简单设置：通过安装程序和 API 密钥，几分钟内即可开始使用
Secure by default: Your code stays on Github's runners
默认安全：您的代码保留在 GitHub 的运行器上
二、What can Claude do?
二、Claude 能做什么？
Claude Code provides a powerful GitHub Action that transforms how you work with code:
Claude Code 提供了强大的 GitHub 操作，它改变了您处理代码的方式：
2.1 Claude Code Action
This GitHub Action allows you to run Claude Code within your GitHub Actions workflows. You can use this to build any custom workflow on top of Claude Code.
这个 GitHub Action 允许你在 GitHub Actions 工作流中运行 Claude Code。你可以使用它来构建基于 Claude Code 的任何自定义工作流。
The easiest way to set up this action is through Claude Code in the terminal. Just open claude and run /install-github-app.
设置这个 Action 最简单的方法是通过终端中的 Claude Code。只需打开 claude 并运行 /install-github-app。
This command will guide you through setting up the GitHub app and required secrets.
这个命令将指导你设置 GitHub App 和所需密钥。
You must be a repository admin to install the GitHub app and add secrets.
你必须是代码仓库管理员才能安装 GitHub 应用并添加密钥。
The GitHub app will request read & write permissions for Contents, Issues, and Pull requests.
GitHub App 将请求对 Contents、Issues 和 Pull Requests 的读写权限。
This quickstart method is only available for direct Claude API users. If you're using AWS Bedrock or Google Vertex AI, please see the Using with AWS Bedrock & Google Vertex AI section.
这种快速入门方法仅适用于直接使用 Claude API 的用户。如果你使用的是 AWS Bedrock 或 Google Vertex AI，请参阅后面的'与 AWS Bedrock & Google Vertex AI 一起使用'部分。
3.2 Manual setup
3.2 手动设置
If the /install-github-app command fails or you prefer manual setup, please follow these manual setup instructions:
如果 /install-github-app 命令失败或你更喜欢手动设置，请按照这些手动设置说明进行操作：
3.2.2 Add ANTHROPIC_API_KEY to your repository secrets (Learn how to use secrets in GitHub Actions)
将 ANTHROPIC_API_KEY 添加到您的仓库密钥中（学习如何在 GitHub Actions 中使用密钥）
3.2.3 Copy the workflow file from examples/claude.yml into your repository's .github/workflows/
将 workflow 文件从 examples/claude.yml 复制到您的仓库的 .github/workflows/
After completing either the quickstart or manual setup, test the action by tagging @claude in an issue or PR comment.
完成快速入门或手动设置后，通过在 Issue 或 PR 评论中使用 @claude 进行测试。
四、Upgrading from Beta
四、从 Beta 版本升级
Claude Code GitHub Actions v1.0 introduces breaking changes that require updating your workflow files in order to upgrade to v1.0 from the beta version.
Claude Code GitHub Actions v1.0 引入了破坏性变更，需要更新你的工作流文件才能从 Beta 版本升级到 v1.0。
If you're currently using the beta version of Claude Code GitHub Actions, we recommend that you update your workflows to use the GA version. The new version simplifies configuration while adding powerful new features like automatic mode detection.
如果你目前正在使用 Claude Code GitHub Actions 的 Beta 版本，我们建议你更新你的工作流以使用正式版本。新版本简化了配置，同时添加了自动模式检测等强大的新功能。
4.1 Essential changes
4.1 重要变更
All beta users must make these changes to their workflow files in order to upgrade:
所有 Beta 版本用户必须对其工作流文件进行这些更改以进行升级：
Update the action version: Change @beta to @v1
更新操作版本：将 @beta 更改为 @v1
Move CLI options: Convert max_turns, model, custom_instructions, etc. to claude_args
移动了 CLI 选项：将 max_turns、model、custom_instructions 等转换为 claude_args
4.2 Breaking Changes Reference
4.2 重大变更参考
Mode: (Removed - auto-detected) (已移除 - 自动检测)
Direct Prompt: Changed to prompt
Override Prompt: prompt with GitHub variables
Custom Instructions: claude_args: --system-prompt
Max Turns: claude_args: --max-turns
Model: claude_args: --model
Allowed Tools: claude_args: --allowedTools
Disallowed Tools: claude_args: --disallowedTools
Claude Env: Settings JSON format
4.3 Before and After Example
4.3 前后示例
Beta version:
-uses:anthropics/claude-code-action@betawith:mode:"tag"direct_prompt:"Review this PR for security issues"anthropic_api_key:${{secrets.ANTHROPIC_API_KEY}}custom_instructions:"Follow our coding standards"max_turns:"10"model:"claude-sonnet-4-5-20250929"
GA version (v1.0):
-uses:anthropics/claude-code-action@v1with:prompt:"Review this PR for security issues"anthropic_api_key:${{secrets.ANTHROPIC_API_KEY}}claude_args:|
--system-prompt "Follow our coding standards"
--max-turns 10
--model claude-sonnet-4-5-20250929
The action now automatically detects whether to run in interactive mode (responds to @claude mentions) or automation mode (runs immediately with a prompt) based on your configuration.
该操作现在会根据您的配置自动检测是否以交互模式运行（响应 @claude 引用）或自动化模式运行（立即使用提示运行）。
五、Example use cases
五、示例
Claude Code GitHub Actions can help you with a variety of tasks. The examples directory contains ready-to-use workflows for different scenarios.
Claude Code GitHub Actions 可以帮助您处理各种任务。示例目录包含适用于不同场景的现成工作流。
5.1 Basic workflow
5.1 基本工作流
name:ClaudeCodeon:issue_comment:types: [created]
pull_request_review_comment:types: [created]
jobs:claude:runs-on:ubuntu-lateststeps:-uses:anthropics/claude-code-action@v1with:anthropic_api_key:${{secrets.ANTHROPIC_API_KEY}}# Responds to @claude mentions in comments
name:DailyReporton:schedule:-cron:"0 9 * * *"jobs:report:runs-on:ubuntu-lateststeps:-uses:anthropics/claude-code-action@v1with:anthropic_api_key:${{secrets.ANTHROPIC_API_KEY}}prompt:"Generate a summary of yesterday's commits and open issues"claude_args:"--model claude-opus-4-5-20251101"
5.4 Common use cases
5.4 常见用例
In issue or PR comments:
在 Issue 或 PR 评论中：
@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
修复用户仪表板组件中的 TypeError 错误
Claude will automatically analyze the context and respond appropriately.
Claude 将自动分析上下文并作出适当回应。
六、Best practices
六、最佳实践
6.1 CLAUDE.md configuration
6.1 CLAUDE.md 配置
Create a CLAUDE.md file in your repository root to define code style guidelines, review criteria, project-specific rules, and preferred patterns. This file guides Claude's understanding of your project standards.
在你的仓库根目录中创建一个 CLAUDE.md 文件来定义代码风格指南、审查标准、项目特定规则和首选模式。该文件指导 Claude 对你的项目标准的理解。
6.2 Security considerations
6.2 安全注意事项
Never commit API keys directly to your repository.
切勿将 API 密钥直接提交到你的仓库中。
Always use GitHub Secrets for API keys:
始终使用 GitHub Secrets 存储 API 密钥：
Add your API key as a repository secret named ANTHROPIC_API_KEY
将您的 API 密钥添加为名为 ANTHROPIC_API_KEY 的仓库密钥
Reference it in workflows: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
在作业流程中引用它：anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
Limit action permissions to only what's necessary.
限制操作权限仅限于必要范围。
Review Claude's suggestions before merging.
合并前审查 Claude 的建议。
Always use GitHub Secrets (for example, ${{ secrets.ANTHROPIC_API_KEY }}) rather than hardcoding API keys directly in your workflow files.
始终使用 GitHub 密钥（例如，${{ secrets.ANTHROPIC_API_KEY }}），而不是直接在流程文件中硬编码 API 密钥。
6.3 Optimizing performance
6.3 优化性能
Use issue templates to provide context, keep your CLAUDE.md concise and focused, and configure appropriate timeouts for your workflows.
使用 Issue 模板提供上下文，保持你的 CLAUDE.md 简洁集中，并为你的工作流配置适当的超时。
6.4 CI costs
6.4 CI 成本
When using Claude Code GitHub Actions, be aware of the associated costs:
在使用 Claude Code GitHub Actions 时，请注意相关成本：
6.4.1 GitHub Actions costs:
GitHub Actions 成本：
Claude Code runs on GitHub-hosted runners, which consume your GitHub Actions minutes
Claude Code 在 GitHub 托管的运行器上运行，这些运行器会消耗你的 GitHub Actions 分钟数
6.4.2 API costs:
API 成本：
Each Claude interaction consumes API tokens based on the length of prompts and responses
每次 Claude 交互会根据提示词和响应的长度消耗 API 令牌
Token usage varies by task complexity and codebase size
任务复杂度和代码库大小不同，Token 使用量也不同
6.4.3 Cost optimization tips:
成本优化建议：
Use specific @claude commands to reduce unnecessary API calls
使用特定的 @claude 命令来减少不必要的 API 调用
Configure appropriate --max-turns in claude_args to prevent excessive iterations
在 claude_args 中配置适当的 --max-turns 以防止过度迭代
Set workflow-level timeouts to avoid runaway jobs
设置工作流程级别的超时以避免失控作业
Consider using GitHub's concurrency controls to limit parallel runs
考虑使用 GitHub 的并发控制来限制并行运行
七、Configuration examples
七、配置示例
The Claude Code Action v1 simplifies configuration with unified parameters:
Claude Code Action v1 通过统一的参数简化了配置：
When responding to issue or PR comments, Claude automatically responds to @claude mentions. For other events, use the prompt parameter to provide instructions.
在回复 Issue 或 PR 评论时，Claude 会自动回复 @claude 提及的内容。对于其他事件，使用 prompt 参数提供指示。
八、Troubleshooting
八、故障排除
8.1 Claude not responding to @claude commands
8.1 Claude 没有响应 @claude 命令
Verify the GitHub App is installed correctly, check that workflows are enabled, ensure API key is set in repository secrets, and confirm the comment contains @claude (not /claude).
验证 GitHub App 是否正确安装，检查工作流是否已启用，确保 API 密钥已设置在仓库密钥中，并确认评论包含 @claude（而不是 /claude）。
8.2 CI not running on Claude's commits
8.2 CI 未运行于 Claude 的提交
Ensure you're using the GitHub App or custom app (not Actions user), check workflow triggers include the necessary events, and verify app permissions include CI triggers.
确保你正在使用 GitHub App 或自定义应用（而不是 Actions 用户），检查工作流触发器是否包含必要的事件，并验证应用权限是否包括 CI 触发器。
8.3 Authentication errors
8.3 认证错误
Confirm API key is valid and has sufficient permissions. For Bedrock/Vertex, check credentials configuration and ensure secrets are named correctly in workflows.
确认 API 密钥有效且具有足够的权限。对于 Bedrock/Vertex，检查凭证配置并确保工作流中的密钥名称正确。
九、Advanced configuration
九、高级配置
9.1 Action parameters
9.1 操作参数
The Claude Code Action v1 uses a simplified configuration:
Claude Code Action v1 使用简化的配置：
prompt: Instructions for Claude (text or skill like /review)
Claude 的说明（文本或技能，如 /review）
claude_args: CLI arguments passed to Claude Code
传递给 Claude Code 的 CLI 参数
anthropic_api_key: Claude API key
Claude API 密钥
github_token: GitHub token for API access
用于 API 访问的 GitHub 令牌
--max-turns: Maximum conversation turns (default: 10)
--max-turns: 最大对话轮数（默认：10）
--model: Model to use (for example, claude-sonnet-4-5-20250929)
--model: 使用的模型（例如，claude-sonnet-4-5-20250929）
--mcp-config: Path to MCP configuration
--mcp-config: MCP 配置文件路径
--allowed-tools: Comma-separated list of allowed tools
--allowed-tools: 允许使用的工具列表，用逗号分隔
--debug: Enable debug output
--debug: 启用调试输出
9.2 Alternative integration methods
9.2 其他集成方法
While the /install-github-app command is the recommended approach, you can also:
虽然 /install-github-app 命令是推荐的方法，你也可以用下面的方法：
Custom GitHub App: For organizations needing branded usernames or custom authentication flows. Create your own GitHub App with required permissions (contents, issues, pull requests) and use the actions/create-github-app-token action to generate tokens in your workflows.
自定义 GitHub 应用：针对需要品牌化用户名或自定义认证流程的组织。创建具有所需权限（内容、问题、拉取请求）的 GitHub 应用，并使用 actions/create-github-app-token 操作在你的流程中生成令牌。
Manual GitHub Actions: Direct workflow configuration for maximum flexibility
手动 GitHub Actions：直接工作流程配置，实现最大灵活性
MCP Configuration: Dynamic loading of Model Context Protocol servers
MCP 配置：动态加载模型上下文协议服务器
9.3 Customizing Claude's behavior
9.3 自定义 Claude 的行为
You can configure Claude's behavior in two ways:
您可以通过两种方式配置 Claude 的行为：
CLAUDE.md: Define coding standards, review criteria, and project-specific rules in a CLAUDE.md file at the root of your repository. Claude will follow these guidelines when creating PRs and responding to requests.
CLAUDE.md：在仓库根目录中的 CLAUDE.md 文件中定义编码标准、审查标准和特定项目的规则。Claude 在创建 PR 和响应请求时会遵循这些指南。
Custom prompts: Use the prompt parameter in the workflow file to provide workflow-specific instructions. This allows you to customize Claude's behavior for different workflows or tasks.
自定义提示：在流程文件中使用 prompt 参数提供特定于流程的说明。这允许你针对不同的流程或任务自定义 Claude 的行为。
Claude will follow these guidelines when creating PRs and responding to requests.
Claude 在创建 PR 和回复请求时会遵循这些指南。
