加载中

CI/CD 集成与部署

第 12 课6 分钟

在 CI/CD 流水线内以非交互方式运行 Claude Code,对执行过程进行沙盒化以确保长时间运行的智能体安全运行,通过 MCP 集成暴露部署能力,并在智能体真正需要之前演练回滚路径。

发生了什么变化

传统方式AI 原生方式
流水线运行确定性脚本,任何需要判断的事情都要等待人工处理:例如,对不稳定测试进行分类、编写变更日志,或弄清楚构建为何失败。部署和回滚是人在压力下遵循的操作手册。Claude 在流水线中以非交互方式运行判断步骤,在具有受限凭证的沙盒中执行。部署工具通过 MCP 暴露给智能体,因此编写并测试了变更的工作流也可以发布它并回滚它,所有操作都在组织按环境定义的关卡内进行。

入门

  • 前提条件:PR 审查循环中的 AI,以及作为审批关卡的钩子,因为在自动化加速通过这些关卡之前,这些关卡必须先存在。
  • 基础设施:安装了 claude-code-action 的 CI 平台,或任何能够调用 claude -p 的运行器;通过 API 访问模型,或在流量必须保留在组织云协议内时使用 Amazon Bedrock、Microsoft Foundry 或 Vertex AI;用于部署目标的 MCP 服务器;用于智能体作业的沙盒配置文件,不具备常驻的生产凭证。

如何执行

  1. 平台工程师从只读判断步骤开始。在流水线作业中使用 claude -p 对失败的构建进行分类、总结不稳定测试,或起草变更日志。
  2. 在现有关卡之后添加写入步骤,用于修复 lint、更新生成的文档,或通过 @claude 提及处理审查意见等作业。智能体写入的任何内容都会通过分支保护以 PR 的形式到达,智能体没有直接推送到 main 的途径。
  3. 执行过程是沙盒化的。智能体作业在受网络策略约束的容器中运行,使用短期有效的受限令牌,默认情况下不持有生产凭证。
  4. 通过 MCP 暴露部署能力。部署、状态查询和回滚成为工具,按环境进行限定,因此智能体的部署权限是一份允许列表,而不是带有凭证的 shell 脚本。
  5. 按环境对自主权进行分级。在开发环境中,智能体可以自由部署。在生产环境中,智能体准备发布,发布经理对其进行授权,并由钩子强制执行生产关卡。预发布环境则介于两者之间。
  6. 回滚应该是流水线中演练最多的路径,是智能体可以运行的单个命令,并在预发布环境中定期演练。闭环打法(第 6 阶段:维护)会在控制带被突破时调用此回滚,因此必须提前验证其有效性。

实际效果

流水线步骤:

yaml
- name: Triage failed build
  if: failure()
  run: >
    claude -p "Read the build log at out/build.log. Identify the most
    likely cause, say whether the failure looks flaky or real, and write a
    three-line summary for the PR thread." >> triage.md

本示例的其余部分是一家保险公司的客户门户,部署以工具形式暴露,每个环境对应一个 MCP 服务器。允许使用某个 MCP 工具的规则指定的是服务器和工具的名称,而不是工具的参数。因此,每个环境使用独立的服务器,正是这一点让允许列表能够区分预发布环境和生产环境。这些服务器在项目的 .mcp.json 中进行设置:

json
{
  "mcpServers": {
    "deploy-dev": {
      "type": "http",
      "url": "https://deploy.example.com/mcp/dev",
      "headers": { "Authorization": "Bearer ${DEPLOY_DEV_TOKEN}" }
    },
    "deploy-staging": {
      "type": "http",
      "url": "https://deploy.example.com/mcp/staging",
      "headers": { "Authorization": "Bearer ${DEPLOY_STAGING_TOKEN}" }
    },
    "deploy-prod": {
      "type": "http",
      "url": "https://deploy.example.com/mcp/prod",
      "headers": { "Authorization": "Bearer ${DEPLOY_PROD_TOKEN}" }
    }
  }
}

每个服务器都提供相同的三个工具:

工具输入返回
releaseversion,在生产环境中还需要 ticket发布完成后的发布 ID
status无等待至上次发布后五分钟,然后返回该时间段内每个端点的 5xx 错误率
rollback无重新上线的版本

预发布作业在推送到 main 时运行,并预先批准预发布服务器的三个工具,不批准其他任何工具。它只持有预发布令牌,因此另外两个服务器得不到有效令牌,会拒绝该作业。以下是预发布作业的流水线步骤:

yaml
- name: Release to staging and roll back if it is unhealthy
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    DEPLOY_STAGING_TOKEN: ${{ secrets.DEPLOY_STAGING_TOKEN }}   # no other environment's token
  run: >
    claude -p "Release version ${{ github.sha }} of the claims portal to staging,
    then call status. If the 5xx rate on any endpoint is over 1%, roll back.
    Finish with three lines for the release notes: what you released, what status
    reported, and whether you rolled back."
    --allowedTools "mcp__deploy-staging__release,mcp__deploy-staging__status,mcp__deploy-staging__rollback"
    --permission-mode dontAsk >> release-notes.md

在 dontAsk 模式下,Claude Code 会拒绝任何原本会发出提示的调用,因此不在列表中的部署工具会被拒绝,作业永远不会等待回答。

release 工具上的一个 PreToolUse 钩子会按环境做出决定。它在"钩子作为审批关卡"打法中被详细写出,并给出了三个层级:

环境允许列表中的工具release 会发生什么由谁批准
开发release、status、rollback钩子允许它无需任何人
预发布release、status、rollback钩子会询问,或在来自 main 的流水线中允许它工程师,或已批准的合并
生产status、rollback除非钩子允许,否则拒绝发布经理,通过变更工单

在生产环境中,dontAsk 模式仍会运行经 PreToolUse 钩子批准的调用,因此当 release 不在允许列表中时,钩子的 allow 是唯一的通过方式。因此生产环境采用失败即关闭的策略,因为如果钩子未能运行,发布就会被拒绝。rollback 仍保留在允许列表中,因为它是一份提前批准的操作手册。

如果运行器携带了带有 allowManagedHooksOnly 的托管设置,则钩子必须在托管设置中定义;如果带有 allowManagedMcpServersOnly,则服务器必须位于托管允许列表中。

治理考量

治理原则是:智能体可以行动直到生产关卡,但不能越过它。以下控制措施强制执行这一原则。

  • 分支保护将智能体写入的任何内容转化为 PR,没有直接通往 main 的路径。
  • 生产部署钩子会阻止发布,直到指定的发布经理对其进行授权。每次非交互式运行都以智能体自身的身份执行,因此流水线日志能够区分智能体所做的事情和触发它的工程师所做的事情。
  • 按环境划分的权限层级设定了智能体在通往关卡的过程中可以做多少事情。

如何衡量

  • 领先指标:无需呼叫人工即可完成分类的流水线失败占比,取自 CI/CD 流水线日志。
  • 滞后指标:DevOps 研究与评估(DORA)指标,CI 系统和部署工具已经会生成这些指标。