Cloudflare推千万级仓库CI/CD方案，用TypeScript工作流替代YAML

我们正在迈向一个可以在 Cloudflare 上完整存储、构建、测试和部署代码的世界。我们通过 Artifacts 迈出了第一步——这是一种可以扩展到数百万个仓库的版本化代码存储方案。

我们用 CI SDK 将存储、构建和部署步骤串联在一起，该 SDK 基于 Cloudflare Workflows 构建，因此你可以在 Cloudflare 上运行持续集成（CI）流水线。你可以直接将 artifact 推送事件发送到 Workflow，触发一个执行实例——本质上就是一个 CI 任务——只需在你的 wrangler 配置文件中的一个新的 events 字段即可。

然后，直接在 Workflow 中安装 @cloudflare/ci 后，你就可以：

• 自动化构建：在安全隔离的环境中从 Artifacts 仓库编译代码
• 运行 linter 和类型检查：强制执行代码风格、捕获类型错误并标记潜在问题
• 缓存依赖项：运行一次安装即可在 CI 任务中的各个步骤之间复用依赖
• 执行单元测试：验证代码的每个部分是否按预期工作
• 自我修复：集成 AI 审核 agent 来捕获构建中的故障步骤并推送修复提交
• 条件部署：仅在构建步骤成功时自动部署代码

如今，每个人都在构建平台——无论是内部的 vibe coding 平台，还是通过代码定制来扩展其面向客户的产品的延伸。各个平台正在使用 Artifacts 中的数百万个仓库来存储他们的代码以及客户的代码，并在两者之间进行版本控制。但每个团队对 CI/CD 流水线的需求各不相同。对于平台而言，他们可能希望为自己的代码定义一套与客户代码不同的 CI 任务。

在这些平台上构建的许多最终客户不想额外承担管理 CI/CD 流水线的麻烦。相反，平台可以代表他们的客户管理构建过程：编写一次 CI/CD 流水线，并在客户构建的所有应用程序之间共享。平台的部分客户可能希望定义自己的 CI——如果是这样，他们可以编写自己的 Workflow，并通过 dynamic workflows 在自己的仓库上运行自定义 CI 任务。它的妙处在于，你不必二选一：平台管理的 CI 和自定义 CI 可以同时运行在同一个命名空间中。

CI/CD 流水线本质上就是一个 Workflow

在此之前，我们已经具备了所有必要的组件，让平台能够在 Cloudflare 上连接他们的 CI/CD 流水线。现在，我们正在带来更好的开发者体验来简化这一过程。

CI/CD 流水线——通常用 GitHub Actions 来编排——是一系列按特定顺序执行的步骤，其中任何步骤失败都会停止流水线并报告错误。从本质上讲，CI/CD 流水线就是一个 Workflow。YAML 文件定义的 CI/CD 流水线由于其固有的约束很容易变得复杂，这也导致了 YAML 疲劳。但 CI/CD 流水线中的每个步骤都可以简单地转换为 Workflow 的 step.do()。你可以用 TypeScript 而不是 YAML 来定义你的 CI/CD 流水线，以获得更大的定制化和可配置性。

我们正在 CI SDK 中推出新工具，允许你在安全隔离的环境中运行流水线的每个步骤（如 build、lint、typecheck），这些都直接建立在 Cloudflare 开发者平台之上，通过 Workflows 和 Sandbox SDK。此外，你现在可以直接在推送时启动 CI 任务，而无需配置事件订阅、队列和队列消费者。

在此之前，你必须直接调用 Sandbox API 并在 CI 流水线的不同步骤之间自行管理状态。该 SDK 允许你在自己的 Workflow 步骤中运行每个沙箱化命令，提供了 Cloudflare Workflows 内置的重试和超时机制。

你还可以通过缓存步骤结果来加速 CI 流水线——例如你的 install 步骤——这样你就不需要为所有后续操作重新安装。依赖缓存减少了 CI/CD 流水线的延迟，因为每个 CI 步骤都不需要重新运行 install。

要定义你的 CI 任务，你需要做的就是：

1. 定义你的 install 步骤，用于处理任何依赖项（CI 任务需要的外部包或工具），如 bundler（如 esbuild）、linter（如 eslint）或 test runner（如 vitest）。
2. 指定 CI 任务中每个步骤的命令（如 bun run build、bun run test、bun run lint）。依赖项被缓存后，每个 CI 步骤可以并行执行，减少整体运行的延迟。
3. 在 deploy 步骤中传递 wrangler deploy。当 CI 流水线通过时，你的 Worker 会自动部署。

const deps: CiRunnerResult = await ci.runner({
  name: 'install',
  command: 'bun install --frozen-lockfile',
  cache: { inputs: ['package.json', 'bun.lock'] },
});

await Promise.all([
  deps.runner({ name: 'lint', command: 'bun run lint' }),
  deps.runner({ name: 'test', command: 'bun run test' }),
  deps.runner({ name: 'typecheck', command: 'bun run typecheck' }),
  deps.runner({ name: 'build', command: 'bun run build' }),
]);

await deps.runner({
  name: 'deploy',
  command: 'bun wrangler deploy',
  cloudflareCredentials: {
    accountId: this.env.CLOUDFLARE_DEPLOY_ACCOUNT_ID,
  },
});

在 Workflow 中编写你自己的 CI 流水线允许你进行尽可能多的自定义。例如，你可以从你的 CI Workflow 中调用一个 agent 来给你的 CI 任务赋予自我修复功能：如果构建中的某个步骤出错，agent 可以自动修复它，并推送一个提交供你审批。

尝试自我修复 CI Workflow 的示例，包含 Project Think：https://github.com/cloudflare/ci/blob/main/examples/self-healing

编写你自己的 CI Workflow

要编写你自己的 CI Workflow，请从 import { CIWorkflow } from '@cloudflare/ci' 开始。首先从 install 步骤开始：

下载你的依赖项，包括你的 CI 步骤需要的任何外部工具或库（如 vite、react）。

指定你的 lockfile，它追踪你的依赖项是否发生了变化。

通过沙箱快照缓存你的依赖项，以便所有后续步骤都能访问。快照将存储在你账户的 R2 存储桶中。

const deps = await ci.runner({
  name: 'install',
  command: 'bun install --frozen-lockfile',
  cache: { inputs: ['package.json', 'bun.lock'] },
});

然后为构建和检查定义步骤，每个步骤都在自己的安全隔离沙箱环境中执行。

默认情况下，Workflow 中的每个步骤独立启动，这意味着除非另有指定，否则步骤将并发执行。并行运行每个步骤可以减少 CI 运行的延迟。为了确保所有检查在 CI 流水线继续之前完成（例如，在 deploy 步骤开始之前完成 build、lint、test 和 typecheck），请用 Promise.all() 包装：

await Promise.all([
   deps.runner({ name: 'lint', command: 'bun run lint' }),
   deps.runner({ name: 'test', command: 'bun run test' }),
   deps.runner({ name: 'typecheck', command: 'bun run typecheck' }),
   deps.runner({ name: 'build', command: 'bun run build' }),
]);

现在，要真正触发你的 CI Workflow，在你 Worker 的 wrangler 配置中添加一个 events 字段，以及你的 Workflow 和 Artifact 绑定。events 字段是你 triggers 字段内支持的一个新字段。

你之前已经可以通过 Cloudflare Queues 的事件订阅来订阅 Artifacts，并在每次有推送事件时启动构建流水线。但这需要设置事件订阅、队列、消费者和队列处理器。现在，你可以用那个事件来定向一个 Workflow——每次那个事件触发时，它都会启动一个 Workflow 实例。

将 CI Workflow 指定为你的 artifact 推送触发器的目标，以在每个 cf.artifacts.repo.pushed 事件上自动触发一个 Workflow 实例。每个 CI 运行都会作为一个 Workflow 实例显示，这样你就可以在 Workflows 仪表板中直接查看其逐步执行和可观测性。这是一个 Artifacts 优先的集成；即将推出，类型将支持来自你 Cloudflare 账户中各种来源的事件，以允许在整个产品套件中进行程序化消费。

如果你想在你的命名空间中的每个仓库上运行 CI Workflow——例如，如果你是一个在所有客户的仓库上运行 CI 的平台——请在 filter 中省略 repoName，只指定命名空间。

{
  "triggers": {
    "events": [
      {
        "type": "cf.artifacts.repo.pushed",
        // filter is optional. If you don't set repoName we will run the same workflow for every push on any repo in your Artifacts namespace
        "filter": {
          "namespace": "CI",
          "repoName": "my-repo"
        },
        "target": {
          "type": "workflow",
          "workflow_name": "ci-workflow"
        }
      }
    ]
  }
}

要完全配置你的 CI Workflow，请将绑定添加到为流水线提供支持的每个基础设施部分：artifacts、workflows、containers 和 durable_objects（+ exports config）绑定（用于访问你的沙箱），如果你使用缓存，还要添加一个 r2 绑定。R2 绑定是必需的，因为你的 install 步骤沙箱的快照存储在一个存储桶中。

为了让你的 CI 任务能够自我修复，你需要两个部分：LLM 及其 agent 框架。在上面的示例中，我们包含了一个使用 Workers AI 的 Think agent 来捕获流水线中的错误并代表你运行修复。你的 CI 任务可以远程运行和重新运行——无需保持笔记本打开或每隔几分钟检查一次。相反，Cloudflare 在云端处理它，在容器中与 CI 步骤一起运行你的修复 agent。不必盯着 CI 任务、进行手动修复并重新运行流水线，你只需要在 agent 完成修复后合并提交即可。

要设置一个自我修复 CI 流水线的 agent，请为你的 Think agent 添加一个 Durable Object 绑定：

"durable_objects": {
   "bindings": [
     {
       "name": "HEALER",
       "class_name": "Healer",
     },
   ],
 },

通过扩展 HealingAgent 类来创建你的 Think agent（Healer），它包含一个你可以在失败时调用的 heal 方法。传递你想使用的模型：

export class Healer extends HealingAgent {
 getModel() {
   return '@cf/moonshotai/kimi-k2.7-code';
 }
}

然后，用 try/catch 块包装你的步骤，其中失败会触发修复 agent：

let deps: CiRunnerResult;
try {
  // Install once, then run independent checks from the shared and cached snapshot
  deps = await ci.runner({
    name: 'install',
    command: 'bun install --frozen-lockfile',
    cache: { inputs: ['package.json', 'bun.lock'] },
  });

  await Promise.all([
    deps.runner({ name: 'lint', command: 'bun run lint' }),
    deps.runner({ name: 'test', command: 'bun run test' }),
    deps.runner({ name: 'typecheck', command: 'bun run typecheck' }),
    deps.runner({ name: 'build', command: 'bun run build' }),
  ]);
} catch (failure) {
  // This catches both failed Sandbox commands and ordinary Workflow errors.
  // Only failures reported by a runner should be healed; rethrow the rest.
  if (!isCiRunnerFailure(failure)) {
    throw failure;
  }

  // Pass the error along to the agent so that it can fix it
  const healed = await step.do(
    'heal',
    { retries: { limit: 0, delay: 0 }, timeout: '5 hours' },
    async () => {
      const healer = await getAgentByName(this.env.HEALER, event.instanceId);
      using result = await healer.heal({
        failure: enrichFailure({ failure, event, baseBranch }),
        prompt: 'Fix every observed failure without weakening validation.',
      });
      // Report the Fix Branch, its commit, and how many steps it took.
      const { branch, commit, steps } = result;
      return { branch, commit, steps };
    }
  );

  // The source run stays failed; its verified fix lives on another branch
  throw new CiRunFailedWithFix(failure, healed);
}

await deps.runner({
  name: 'deploy',
  command: 'bun wrangler deploy',
});

这个示例展示了一个自我修复的 CI 流水线，但真正重要的是，BYO-Workflow 模型允许你随心所欲地定制 CI 任务。这里可以添加安全规则、过滤器或条件性 CI 步骤。使用 BYO-W 模型，平台可以根据每个单独的使用案例为不同的团队、客户或应用程序配置他们的 CI/CD 流水线。

使用 Workflow 的好处

通过在 Cloudflare Workflow 上运行 CI 流水线，你自动继承以下能力：

弹性重试（持久执行）：如果 CI 任务中的任何步骤失败，它会自动重试并保持状态，这意味着不会丢失任何进度。每个步骤都支持自定义重试和超时行为，因此你可以为每个步骤定义不同的失败逻辑。此外，你可以从特定步骤重新启动，因此如果只是 lint 失败了，你不必重新运行整个 CI 流水线。

Workflows 可观测性：在 Workflows 仪表板中逐步检查你的 CI 任务，每个实例都会显示带有输入、输出以及 wall 时间和 CPU 时间的步骤。你可以通过仪表板中的 Workflows 图表可视化你的 CI 任务，让你轻松查看哪些步骤是并发运行还是顺序运行。你还可以通过 Workers Observability 和 GraphQL 检查 Workflows 日志，以更好地了解 CI 任务的运行情况。

代码的力量：通过在 Workflow 中运行 CI，你可以为任何你想要的东西编写一个步骤。例如，你可能希望将 AI 代码审查器作为 CI/CD 流水线的一部分来运行。你可以通过 Workflows 的 step.do() 调用你的代码审查 agent——或处理任何你能用代码实现的自定义逻辑。其他示例可能包括将构建产物写入 R2 以及在 CI 失败、完成或合并到 main 时发送电子邮件。

CI/CD 流水线本质上就是一个 Workflow——通过 CI SDK，你可以用简单的 TypeScript 而非僵化的 YAML 来定义你和客户代码的 CI。基于 Cloudflare Workflows 的原语，你可以定义任何你想要的逻辑，无论是像我们的 Think 示例中的修复 agent，还是将构建产物写入 R2。在 Workflows 上运行 CI 有助于弥合存储（通过 Artifacts）、构建和部署之间的鸿沟。作为一个平台，这让你能够轻松地管理自己和代表客户的每个步骤。

申请加入 Artifacts 私有测试版并开始使用我们的 Workflows CI 指南。如果你有任何功能请求或发现任何错误，请通过加入 Discord 上的 Cloudflare Developers 社区直接与 Cloudflare 团队分享你的反馈。

• Workers 和 Workers for Platforms 的直接集成：build.preview() 和 build.deploy() 原语，用于在推送到 main 时自动部署和在推送到非默认分支时创建预览
• 渐进式部署：通过 Workflows 管理基于百分比的发布，以自定义你的部署进度和回滚逻辑
• Monorepos：使用一个 CI 流水线简化多 Worker 部署的管理
• Triggers：从不同来源发送推送事件，以从任何版本控制系统（而不仅仅是 Artifacts）在仓库上运行 CI 任务