Claude Code Action 实战指南：为 GitHub PR 与 Issue 接入智能代码助手与自动化工作流

Claude Code Action 实战指南为 GitHub PR 与 Issue 接入智能代码助手与自动化工作流【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-actionClaude Code Action 是一个通用型 GitHub Actions 组件它把 Claude Code 的能力直接注入仓库的 PR 与 Issue 流程既能回答代码问题、做代码评审、实现代码修改也能执行带明确指令的自动化任务。它根据工作流上下文智能判断何时激活响应 claude 提及、Issue 指派、或执行带显式 prompt 的自动化任务并支持 Anthropic 直连 APIAPI Key 或 workload identity federation、Amazon Bedrock、Google Vertex AI 与 Microsoft Foundry 等多种认证方式。读完本文你将掌握该 Action 的安装配置、全部输入参数、模式检测原理、结构化输出用法以及从 v0.x 到 v1.0 的迁移路径。项目定位跑在你自己的 Runner 上的代码助手Claude Code Action 面向的是一类典型场景你希望有一个真正能动手改代码的 AI 助手长驻在 GitHub 仓库中而不只是生成一段建议。它的执行完全发生在你自己的 GitHub Runner 上Anthropic API 调用会发往你选择的供应商因此数据不出仓库PR/Issue 上下文在 Runner 内被拉取并交给 Claude Code执行产物直接回写为评论、分支或 Action outputs可观测、可审计每次执行都有执行文件execution file与 step summary运行过程可在 Actions 日志中完整回放灵活可控通过统一的prompt与claude_args输入对齐 Claude Code SDK配置简洁而强大。核心特性一览特性说明智能模式检测根据工作流上下文自动选择执行模式tag / agent无需手动配置mode交互式代码助手Claude 可以回答关于代码、架构和编程的问题代码评审分析 PR 变更并提出改进建议✨代码实现能实现简单修复、重构甚至是新功能PR/Issue 集成与 GitHub 评论和 PR review 无缝协作️灵活的工具访问可访问 GitHub API 与文件操作可通过配置启用更多工具进度跟踪用复选框显示可视化进度指示随 Claude 完成任务动态更新结构化输出获得校验过的 JSON 结果自动成为 GitHub Action outputs支撑复杂自动化运行在你的基础设施上整个 Action 完全运行在你自己的 GitHub Runner 上⚙️简化的配置统一的prompt与claude_args输入与 Claude Code SDK 对齐模式检测的源码实现智能模式检测并非营销话术其实现位于 src/modes/detector.ts 的detectMode()函数。从源码结构看检测逻辑的决策树如下注释类事件issue_comment、pull_request_review_comment、pull_request_review提供了prompt输入 → 判定为agent模式评论中包含触发短语默认claude→ 判定为tag模式Issue 事件issues同样优先看prompt否则检查 claude 提及或 label/assignee 触发PR 事件pull_request的opened/synchronize/ready_for_review/reopened动作提供prompt即进入agent模式兜底默认返回agent模式没有 prompt 时不会触发执行。此外track_progress输入会在 PR/Issue 类事件上强制走tag模式并启用跟踪评论且只对pull_request、issues、issue_comment、pull_request_review_comment、pull_request_review这几类事件有效detector.ts 中有严格的校验其他事件会直接抛错。整个执行编排集中在统一的 src/entrypoints/run.ts它依次完成解析上下文 → 检测模式 → 配置 GitHub Token → 校验写权限 → 检查触发条件 → prepare创建跟踪评论/分支→ 安装 Claude Code CLI失败自动重试最多 3 次→ 运行 Claude → 更新评论与 step summary。快速上手两种启动方式方式一终端一键安装推荐最简单的方式是通过终端里的 Claude Code 完成设置打开claude后运行/install-github-app该命令会引导你完成 GitHub App 的安装与所需 secrets 的配置。注意你必须具备仓库管理员权限才能安装 GitHub App 和添加 secrets该快速上手方式仅适用于 Anthropic 直连 API 用户。AWS Bedrock、Google Vertex AI 或 Microsoft Foundry 的配置请参考 docs/cloud-providers.md。方式二手动配置Direct API将 Claude GitHub App 安装到你的仓库https://github.com/apps/claude在仓库 secrets 中添加认证信息Settings → Secrets and variables → ActionsANTHROPIC_API_KEYAnthropic API Key以sk-ant-开头或CLAUDE_CODE_OAUTH_TOKENClaude Code OAuth tokenPro/Max 用户可本地运行claude setup-token生成将 examples/claude.yml 中的工作流文件复制到你的仓库.github/workflows/目录。如果完全不想存储静态 API Key可以改用 Workload Identity Federation见下文。Workload Identity Federation免静态密钥认证WIF 通过把工作流的 GitHub Actions OIDC token 交换为短期有效的 Anthropic 访问令牌来认证无需创建、存储或轮换ANTHROPIC_API_KEY。一次性配置在 Claude Console 中——需要 Anthropic 组织管理员权限Console → Settings → Workload identity为 GitHub Actions 注册 issuerissuer URL 为https://token.actions.githubusercontent.comJWKS source:discovery创建 service accountSettings → Service accounts并加入目标 workspace记下svac_...ID创建 federation rule 指向该 service account匹配仓库的 OIDC claims例如 subject 前缀repo:your-org/your-repo:记下fdrl_...规则 ID。工作流配置示例jobs: claude-response: runs-on: ubuntu-latest permissions: contents: write pull-requests: write issues: write id-token: write # 必需用于获取 GitHub OIDC token steps: - uses: anthropics/claude-code-actionv1 with: anthropic_federation_rule_id: fdrl_xxxxxxxxxxxx anthropic_organization_id: 00000000-0000-0000-0000-000000000000 anthropic_service_account_id: svac_xxxxxxxxxxxx # federation rule 指向单一 workspace 时可省略 anthropic_workspace_id: wrkspc_xxxxxxxxxxxx这些值都是标识符而非凭据可以直接写在工作流文件或仓库变量中。要点工作流必须授予id-token: write权限不要与anthropic_api_key/claude_code_oauth_token同时设置——静态凭据优先federation 将不会启用GitHub OIDC token 默认请求 audiencehttps://api.anthropic.com因此 federation rule 的预期 audience 应设为该值或留空不匹配仅在规则需要不同 audience 时才用anthropic_oidc_audience内联评论分类classify_inline_comments目前依赖anthropic_api_key使用 federation 时该功能被跳过未确认的内联评论会被直接发布。使用自定义 GitHub App若不想安装官方 Claude App需要更严格的权限、组织策略禁止第三方 App、或正在使用 AWS Bedrock / Google Vertex AI可以创建自己的 GitHub App快速方式下载本仓库的快速配置工具 docs/create-app.html在浏览器中打开点击 Create App for Personal Account 或填写组织名后点击 Create App for Organization工具会自动配置全部所需权限并提交 manifest也可以直接使用 github-app-manifest.json 走 GitHub 的 Create from manifest 流程手动方式在 GitHub 创建 App 时配置最小权限——Repository permissions 下 Contents / Issues / Pull requests 均为 Read Write然后生成并下载私钥.pem将APP_ID与APP_PRIVATE_KEY存入仓库 secrets最后用actions/create-github-app-tokenv1生成 token 并通过github_token输入传入 Action。完整工作流配置与输入参数详解一个最基础的工作流文件完整版见 examples/claude.yml事件触发版见 examples/issue-triage.ymlname: Claude Assistant on: issue_comment: types: [created] pull_request_review_comment: types: [created] issues: types: [opened, assigned, labeled] pull_request_review: types: [submitted] jobs: claude-response: runs-on: ubuntu-latest steps: - uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # 或使用 OAuth token # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} # 可选自动化工作流提供 prompt # prompt: Review this PR for security issues # 可选向 Claude CLI 传递高级参数 # claude_args: | # --max-turns 10 # --model claude-4-0-sonnet-20250805 # 可选添加自定义插件 marketplace # plugin_marketplaces: https://github.com/user/marketplace1.git\nhttps://github.com/user/marketplace2.git # 可选安装 Claude Code 插件 # plugins: code-reviewclaude-code-plugins\nfeature-devclaude-code-plugins # 可选自定义触发短语默认 claude # trigger_phrase: /claude # 可选Issue 指派触发用户名 # assignee_trigger: claude # 可选Issue 标签触发 # label_trigger: claude # 可选授予额外权限需 GitHub token 有相应权限 # additional_permissions: | # actions: read # 可选允许机器人触发 # allowed_bots: dependabot[bot],renovate[bot]输入参数全表以下是 docs/usage.md 与 action.yml 中定义的全部输入参数输入说明必填默认值anthropic_api_keyAnthropic API Key直连 API 必需Bedrock/Vertex/Foundry 不需要否*-claude_code_oauth_tokenClaude Code OAuth tokenanthropic_api_key的替代否*-anthropic_federation_rule_idWorkload identity federation 规则 IDfdrl_...与anthropic_organization_id配合用工作流 OIDC token 认证替代静态 API Key否*-anthropic_organization_id用于 WIF 的 Anthropic 组织 UUID否*-anthropic_service_account_id联邦 token 以哪个 service account 身份生效svac_...可选否-anthropic_workspace_idWIF 的 workspace IDwrkspc_...federation rule 指向单一 workspace 时可省略否-anthropic_oidc_audience请求 GitHub OIDC token 时使用的 audience否https://api.anthropic.comprompt给 Claude 的指令可以是直接 prompt 或自动化工作流的自定义模板否-track_progress强制 tag 模式并启用跟踪评论仅适用于特定 PR/Issue 事件否falseinclude_fix_links在 PR 评审反馈中包含 Fix this 链接可打开带上下文的 Claude Code 修复问题否trueclaude_args直接传给 Claude CLI 的附加参数如--max-turns 10 --model claude-4-0-sonnet-20250805否base_branch创建新分支时使用的基线分支如main、develop否-use_sticky_comment仅用一个评论承载 PR 评论只适用于 pull_request 事件工作流否falseclassify_inline_comments缓存未带confirmed: true的内联评论会话结束后用 Haiku 分类真实评审 vs 测试/探测防止子代理测试评论设为false则立即发布所有内联评论否truegithub_token供 Claude 操作的 GitHub token。只有使用自定义 GitHub App 时才需要提供否-use_bedrock使用 Amazon BedrockOIDC 认证替代 Anthropic 直连 API否falseuse_vertex使用 Google Vertex AIOIDC 认证替代 Anthropic 直连 API否falseuse_foundry使用 Microsoft FoundryOIDC 认证替代 Anthropic 直连 API否falseassignee_trigger触发 Action 的被指派用户名如 claude仅用于 Issue 指派否-label_trigger应用到 Issue 上即触发 Action 的标签名如 claude否-trigger_phrase在评论、Issue/PR 正文与标题中查找的触发短语否claudebranch_prefixClaude 分支的前缀默认claude/claude-为短横线格式否claude/branch_name_template分支命名模板可用变量{{prefix}}、{{entityType}}、{{entityNumber}}、{{timestamp}}、{{sha}}、{{label}}、{{description}}{{label}}取 Issue/PR 第一个标签否则回退为{{entityType}}{{description}}取 Issue/PR 标题前 5 个词的 kebab-case 形式默认{{prefix}}{{entityType}}-{{entityNumber}}-{{timestamp}}否settingsClaude Code settingsJSON 字符串或 settings JSON 文件路径否additional_permissions需要启用的额外权限目前支持actions: read等否use_commit_signing用 GitHub API 启用提交签名简单但无法执行 rebase 等复杂 git 操作否falsessh_signing_key用于提交签名的 SSH 私钥支持完整 git CLI 操作rebase 等优先级高于use_commit_signing否bot_idgit 操作使用的 GitHub 用户 ID默认 Claude 的 bot ID配合ssh_signing_key实现已验证提交否41898282bot_namegit 操作使用的 GitHub 用户名默认 Claude 的 bot 名否claude[bot]include_comments_by_actor逗号分隔的、要包含其评论的 actor 用户名列表支持*[bot]通配符匹配所有 bot空默认表示包含所有 actor否exclude_comments_by_actor逗号分隔的、要排除其评论的 actor 用户名列表支持*[bot]通配符同时命中两个列表时排除优先否allowed_bots允许的 bot 用户名列表或*允许所有 bot空串默认不允许任何 bot。⚠️ 在公开仓库使用*时外部 App 可能可以调用此 Action否allowed_non_write_users⚠️ 高风险允许无写权限用户的用户名列表或*允许所有用户仅在使用github_token输入时生效否path_to_claude_code_executable自定义 Claude Code 可执行文件路径跳过自动安装适用于 Nix、自定义容器等场景否path_to_bun_executable自定义 Bun 可执行文件路径跳过自动安装适用于 Nix、自定义容器等场景否plugin_marketplaces换行分隔的 Claude Code 插件 marketplace Git URL 列表在安装插件前添加否plugins换行分隔的 Claude Code 插件名列表在 Claude Code 执行前安装否display_report是否在 GitHub Step Summary 中显示 Claude Code Report使用自定义格式化方案时设为false否falseshow_full_output显示 Claude Code 的完整 JSON 输出。⚠️ 会输出全部消息包括工具执行结果可能包含 secrets/API Key 等敏感信息且公开可见于 Actions 日志仅在非敏感环境调试时开启否false* 使用 Anthropic 直连 API默认且未使用 Bedrock/Vertex 时为必填。已弃用输入及迁移路径以下输入已弃用将在未来版本移除输入说明迁移路径mode已弃用模式现在根据工作流上下文自动检测删除该输入即可direct_prompt已弃用改用prompt替换为promptoverride_prompt已弃用改用带模板变量的prompt或claude_args的--system-prompt模板用prompt系统提示用claude_argscustom_instructions已弃用改用claude_args的--append-system-prompt或并入prompt移入prompt或claude_argsmax_turns已弃用改用claude_args的--max-turns使用claude_args: --max-turns 5model已弃用改用claude_args的--model使用claude_args: --model claude-4-0-sonnet-20250805fallback_model已弃用在claude_args中配置 fallback在claude_args或settings中配置allowed_tools已弃用改用claude_args的--allowedTools使用claude_args: --allowedTools Edit,Read,Writedisallowed_tools已弃用改用claude_args的--disallowedTools使用claude_args: --disallowedTools WebSearchmcp_config已弃用改用claude_args的--mcp-config使用claude_args: --mcp-config {...}claude_env已弃用改用settings的 env 配置在settingsJSON 中配置环境变量注意该 Action 目前处于 beta 阶段功能与 API 可能随集成持续改进而变化。常用进阶配置自定义 MCP 服务器通过claude_args的--mcp-config添加自定义 MCP 服务器会与内置的 GitHub MCP 服务器合并。例如添加一个顺序思考服务器- uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --mcp-config {mcpServers: {sequential-thinking: {command: npx, args: [-y, modelcontextprotocol/server-sequential-thinking]}}} --allowedTools mcp__sequential-thinking__sequentialthinking需要向 MCP 服务器传递 API Key 等敏感信息时先在工作流步骤中用 GitHub Secrets 生成配置文件再传给 Action可以多次使用--mcp-config合并多个服务器。自定义服务器会覆盖同名的内置服务器。详细示例见 docs/configuration.md。授予 CI/CD 访问权限additional_permissions: actions: read配合工作流顶层permissions中的actions: read可以让 Claude 获得以下 MCP 工具mcp__github_ci__get_ci_status— 查看工作流运行状态mcp__github_ci__get_workflow_run_details— 获取详细工作流信息mcp__github_ci__download_job_log— 下载并分析任务日志之后你就可以在评论里问 claudewhy did the CI fail?。actions: read、checks: read、discussions: read/write、workflows: read/write都是可请求的额外权限contents: write、pull_requests: write、issues: write等标准权限始终包含无需指定。工具权限、模型与会话控制默认工具集默认只有文件操作读、提交、编辑文件只读 git 命令、评论管理和基础 GitHub 操作默认不允许执行任意 Bash 命令。要允许特定命令需显式配置claude_args: --allowedTools Bash(npm install),Bash(npm run test),Edit,Replace,NotebookEditCell用--disallowedTools禁用限制对话轮次claude_args: --max-turns 5可控制成本、防止失控对话自定义模型claude_args: --model claude-4-0-sonnet-20250805Bedrock 用--model anthropic.claude-4-0-sonnet-20250805-v1:0Vertex 用--model claude-4-0-sonnet20250805通过 Anthropic 兼容网关访问 1M 上下文模型时用--model claude-opus-5[1m]显式启用 1M 上下文窗口settings 输入支持 JSON 字符串或文件路径可配置model、env、permissions、hooks等全部 Claude Code settingsAction 始终把enableAllProjectMcpServers置为trueclaude_args优先级高于settings。结构化输出让 Claude 的结果进入自动化流水线结构化输出能把 Claude 的 JSON 结果自动变成 GitHub Action outputs从而构建Claude 分析数据 → 后续步骤使用结果的复杂自动化。基本示例检测 flaky 测试- name: Detect flaky tests id: analyze uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | Check the CI logs and determine if this is a flaky test. Return: is_flaky (boolean), confidence (0-1), summary (string) claude_args: | --json-schema {type:object,properties:{is_flaky:{type:boolean},confidence:{type:number},summary:{type:string}},required:[is_flaky]} - name: Retry if flaky if: fromJSON(steps.analyze.outputs.structured_output).is_flaky true run: gh workflow run CI工作原理定义 Schema在claude_args中用--json-schema提供 JSON SchemaClaude 执行Claude 使用工具完成你的任务校验输出结果会按你的 schema 校验JSON 输出所有字段打包进单个structured_outputJSON 字符串。读取结构化输出在 GitHub Actions 表达式中fromJSON(steps.analyze.outputs.structured_output).is_flaky在 bash 中配合 jqecho $OUTPUT | jq -r .is_flaky。注意受 GitHub Actions 限制composite action 无法暴露动态 outputs因此所有字段都打包在单个structured_outputJSON 字符串中。完整示例examples/test-failure-analysis.yml 是一个可直接运行的完整案例它监听workflow_run事件在 CI 失败时让 Claude 判断是否为 flaky 测试输出is_flaky、confidence、summary三个字段然后高置信度≥ 0.7自动重跑工作流、低置信度跳过并提示人工复查、PR 构建时自动在 PR 上评论分析结论。解决方案与用例仓库的 docs/solutions.md 提供了大量开箱即用的自动化模式每套方案都包含完整可运行的示例、配置细节与预期结果自动 PR 代码评审— 完整的评审自动化路径特定评审— 只在关键文件变更时触发外部贡献者评审— 对新贡献者的特殊处理自定义评审清单— 强制执行团队规范定时维护— 自动化仓库健康检查️Issue 分类与打标签— 自动归类文档同步— 让文档随代码变更保持更新安全聚焦评审— 对齐 OWASP 的安全分析DIY 进度跟踪— 在自动化模式下创建跟踪评论对应的可运行示例文件还包括 examples/pr-review-comprehensive.yml、examples/pr-review-filtered-authors.yml、examples/pr-review-filtered-paths.yml、examples/ci-failure-auto-fix.yml、examples/issue-deduplication.yml、examples/issue-triage.yml、examples/manual-code-analysis.yml 等。用 claude 触发交互默认情况下只要在 PR 或 Issue 评论中提及claude就会触发 Action也可用trigger_phrase自定义触发短语。Claude 能看到完整的 PR 上下文包括所有评论。提问claude What does this function do and how could we improve it?Claude 会分析代码并提供详细解释与建议。请求修复claude Can you add error handling to this function?代码评审claude Please review this PR and suggest improvements从截图修复 Bugclaude Heres a screenshot of a bug Im seeing [upload screenshot]. Can you fix it?Claude 能看图分析方便修复视觉/UI 类 Bug。从 v0.x 升级到 v1.0完整的逐步升级指南见 docs/migration-guide.md。核心思路v1.0 简化了配置同时保持与多数现有设置的兼容性。交互式工作流claude 提及升级前v0.x- uses: anthropics/claude-code-actionbeta with: mode: tag anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} custom_instructions: Focus on security max_turns: 10升级后v1.0- uses: anthropics/claude-code-actionv1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --max-turns 10 --append-system-prompt Focus on security自动化工作流升级前v0.x- uses: anthropics/claude-code-actionbeta with: mode: agent direct_prompt: Update the API documentation anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} model: claude-4-0-sonnet-20250805 allowed_tools: Edit,Read,Write升级后v1.0- uses: anthropics/claude-code-actionv1 with: prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} Update the API documentation to reflect changes in this PR anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --model claude-4-0-sonnet-20250805 --allowedTools Edit,Read,Write自定义模板升级前v0.x- uses: anthropics/claude-code-actionbeta with: override_prompt: | Analyze PR #$PR_NUMBER for security issues. Focus on: $CHANGED_FILES升级后v1.0- uses: anthropics/claude-code-actionv1 with: prompt: | Analyze PR #${{ github.event.pull_request.number }} for security issues. Focus on the changed files in this PR.安全最佳实践绝不把 API Key 提交进仓库一律使用 GitHub Actions secretsanthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}所有敏感值API Key、token、凭据都应通过${{ secrets.XXX }}引用尽可能使用短期 token定期轮换 API Key 与 token在公开仓库中谨慎使用allowed_bots: *与allowed_non_write_users可能引入 prompt injection 风险docs/security.md 有详细说明有验证提交需求时可组合使用use_commit_signing或ssh_signing_keySSH 签名支持 rebase 等复杂操作docs/security.md。文档地图文档内容docs/solutions.md 开箱即用的自动化模式docs/migration-guide.md⭐ 从 v0.x 升级到 v1.0docs/setup.md手动安装、自定义 GitHub App 与安全最佳实践docs/usage.md基本用法、工作流配置与输入参数docs/custom-automations.md自动化工作流与自定义 prompt 示例docs/configuration.mdMCP 服务器、权限、环境变量与高级设置docs/experimental.md执行模式与网络限制docs/cloud-providers.mdAWS Bedrock、Google Vertex AI、Microsoft Foundry 配置docs/capabilities-and-limitations.mdClaude 能做什么、不能做什么docs/security.md访问控制、权限与提交签名docs/faq.md常见问题与故障排查FAQ 与 License遇到问题或有疑问请查阅 docs/faq.md 中的常见问题解答以及 Claude 能力与限制的详细说明。本项目采用 MIT License 开源详情见 LICENSE。【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-action创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考