企业官网建设流程全解析

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

【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-action

Claude Code Action 是一个通用型 GitHub Actions 组件，它把 Claude Code 的能力直接注入仓库的 PR 与 Issue 流程：既能回答代码问题、做代码评审、实现代码修改，也能执行带明确指令的自动化任务。它根据工作流上下文智能判断何时激活（响应 @claude 提及、Issue 指派、或执行带显式 prompt 的自动化任务），并支持 Anthropic 直连 API（API 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，配置简洁而强大。

核心特性一览

模式检测的源码实现

"智能模式检测"并非营销话术，其实现位于 src/modes/detector.ts 的detectMode()函数。从源码结构看，检测逻辑的决策树如下：

1. 注释类事件（issue_comment、pull_request_review_comment、pull_request_review）：
   • 提供了prompt输入 → 判定为agent模式；
   • 评论中包含触发短语（默认@claude）→ 判定为tag模式；
2. Issue 事件（issues）：同样优先看prompt，否则检查 @claude 提及或 label/assignee 触发；
3. PR 事件（pull_request的opened/synchronize/ready_for_review/reopened动作）：提供prompt即进入agent模式；
4. 兜底：默认返回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）

1. 将 Claude GitHub App 安装到你的仓库（https://github.com/apps/claude）；
2. 在仓库 secrets 中添加认证信息（Settings → Secrets and variables → Actions）：
   • ANTHROPIC_API_KEY：Anthropic API Key（以sk-ant-开头）；
   • 或CLAUDE_CODE_OAUTH_TOKEN：Claude Code OAuth token（Pro/Max 用户可本地运行claude setup-token生成）；
3. 将 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）：

1. 为 GitHub Actions 注册 issuer，issuer URL 为https://token.actions.githubusercontent.com（JWKS source:discovery）；
2. 创建 service account（Settings → Service accounts）并加入目标 workspace，记下svac_...ID；
3. 创建 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-action@v1 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-token@v1生成 token 并通过github_token输入传入 Action。

完整工作流配置与输入参数详解

一个最基础的工作流文件（完整版见 examples/claude.yml，事件触发版见 examples/issue-triage.yml）：

name: 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-action@v1 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-review@claude-code-plugins\nfeature-dev@claude-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（默认，且未使用 Bedrock/Vertex 时）为必填。

已弃用输入及迁移路径

以下输入已弃用，将在未来版本移除：

注意：该 Action 目前处于 beta 阶段，功能与 API 可能随集成持续改进而变化。

常用进阶配置

自定义 MCP 服务器

通过claude_args的--mcp-config添加自定义 MCP 服务器，会与内置的 GitHub MCP 服务器合并。例如添加一个顺序思考服务器：

- uses: anthropics/claude-code-action@v1 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-20250805；Bedrock 用--model anthropic.claude-4-0-sonnet-20250805-v1:0，Vertex 用--model claude-4-0-sonnet@20250805；通过 Anthropic 兼容网关访问 1M 上下文模型时用--model "claude-opus-5[1m]"显式启用 1M 上下文窗口；
• settings 输入：支持 JSON 字符串或文件路径，可配置model、env、permissions、hooks等全部 Claude Code settings；Action 始终把enableAllProjectMcpServers置为true；claude_args优先级高于settings。

结构化输出：让 Claude 的结果进入自动化流水线

结构化输出能把 Claude 的 JSON 结果自动变成 GitHub Action outputs，从而构建"Claude 分析数据 → 后续步骤使用结果"的复杂自动化。

基本示例：检测 flaky 测试

- name: Detect flaky tests id: analyze uses: anthropics/claude-code-action@v1 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

工作原理

1. 定义 Schema：在claude_args中用--json-schema提供 JSON Schema；
2. Claude 执行：Claude 使用工具完成你的任务；
3. 校验输出：结果会按你的 schema 校验；
4. JSON 输出：所有字段打包进单个structured_outputJSON 字符串。

读取结构化输出

在 GitHub Actions 表达式中：fromJSON(steps.analyze.outputs.structured_output).is_flaky；在 bash 中配合 jq：echo "$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

从截图修复 Bug

@claude Here's a screenshot of a bug I'm 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-action@beta with: mode: "tag" anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} custom_instructions: "Focus on security" max_turns: "10"

升级后（v1.0）：

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

自动化工作流

升级前（v0.x）：

- uses: anthropics/claude-code-action@beta 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-action@v1 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-action@beta with: override_prompt: | Analyze PR #$PR_NUMBER for security issues. Focus on: $CHANGED_FILES

升级后（v1.0）：

- uses: anthropics/claude-code-action@v1 with: prompt: | Analyze PR #${{ github.event.pull_request.number }} for security issues. Focus on the changed files in this PR.

安全最佳实践

• 绝不把 API Key 提交进仓库，一律使用 GitHub Actions secrets：anthropic_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_key（SSH 签名支持 rebase 等复杂操作，docs/security.md）。

文档地图

FAQ 与 License

遇到问题或有疑问，请查阅 docs/faq.md 中的常见问题解答，以及 Claude 能力与限制的详细说明。

本项目采用 MIT License 开源，详情见 LICENSE。

【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-action