Artifacts 事件可以构建并部署存储在 Artifacts 存储库中的项目。当用户或智能体(agent)推送提交时,该事件会触发一个 Workflow 实例。
如果您需要 Worker 的标准构建与部署行为,请使用 Workers Builds Artifacts 集成。Workers Builds 会在您向存储库推送时运行已配置的构建和部署命令,并支持为非生产分支创建 Worker Previews。
当您需要自定义持续集成(CI)流水线时,请继续阅读本指南。例如,使用此工作流可以并行运行多项检查、跨 runner 缓存依赖项、部署到 Workers for Platforms,或应用自定义重试和凭据设置。
在 Workflow 中,您可以使用 @cloudflare/ci SDK 定义 CI 流水线,以缓存依赖项、运行检查并构建项目。CI 流水线的最后一步可以将输出部署到 Worker 或 Workers for Platforms User Worker。
在需要执行以下操作时,这会很有用:
- 自动构建并部署存储在 Artifacts 中的应用代码。
- 在每次推送时运行 lint、类型检查、测试以及其他检查。
- 在锁文件(例如
pnpm-lock.yaml)未变更时复用依赖项。 - 在检查或构建失败时停止部署。
- 将 API 令牌访问权限限制在部署步骤。
- 将输出部署到 Worker 或 Workers for Platforms User Worker。
- 推送存储库变更 — 向 Artifacts 存储库执行
git push会发出artifacts.repo.pushed事件,该事件会标识被推送的存储库、分支和提交。 - 运行 CI Workflow — 该事件会启动一个 Workflow:检出提交、安装并缓存依赖项,然后并行运行 CI 步骤(build、lint、typecheck 和 format)。若某一步失败,会在部署前停止 Workflow。
- 部署 Worker — Workflow 会将构建好的 Worker 直接部署到您的账户,或在使用 Workers for Platforms 时部署为 User Worker。
使用 @cloudflare/ci SDK 定义 CI 步骤。该 SDK 提供两个工具来帮助您构建流水线:
- Runners — 每次调用
runner()都会启动一个隔离的沙箱并执行一条 shell 命令。您可以使用已经在本地或其他 CI 系统中运行的相同命令。每个 runner 都会捕获自己的日志、状态和输出文件。 - Cache — runner 上的
cache选项会缓存已安装的依赖项,以便后续运行无需重新安装。将决定依赖项的文件(例如pnpm-lock.yaml)传给cache.inputs。当这些文件未变更时,SDK 会恢复缓存结果,而不是再次运行该命令。
已缓存的 runner 会为其沙箱拍摄快照(snapshot),供后续 runner 复用。多个 runner 可以从同一缓存结果分支——例如,lint、类型检查和测试 runner 都可以复用一次已缓存的安装。
失败的 runner 会按其步骤配置重试,您可以在其中定义重试次数、退避策略和超时。依赖上一步的 runner 只有在该步重试成功后才会启动。如果达到配置的重试上限,Workflow 会以 Errored 状态终止。
以下示例展示如何设置 Workflow,使用 runner 和缓存来安装依赖项、运行检查、构建项目并部署 Worker:
import { CIWorkflow } from "./src/pipeline";
export class CI extends CIWorkflow {
async pipeline(_event, _step, ci) {
// Install once, then run independent checks from the shared snapshot.
const 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" }),
]);
await deps.runner({
name: "deploy",
command: "bun wrangler deploy",
cloudflareCredentials: {
accountId: this.env.CLOUDFLARE_DEPLOY_ACCOUNT_ID,
},
});
}
}import { CIWorkflow } from "./src/pipeline";
import type {
CiContext,
CiParams,
CiRunnerResult,
CloudflareArtifacts,
} from "./src/pipeline";
import type { WorkflowEvent, WorkflowStep } from "cloudflare:workers";
export class CI extends CIWorkflow {
protected async pipeline(
_event: WorkflowEvent<CiParams<CloudflareArtifacts>>,
_step: WorkflowStep,
ci: CiContext,
): Promise<void> {
// Install once, then run independent checks from the shared snapshot.
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,
},
});
}
}当用户或智能体(agent)向 Artifacts 存储库推送提交时,Artifacts 会发出一个事件,标识发生变更的存储库、分支和提交。您将使用此事件触发 Workflow 实例;该实例会运行 CI 流水线:自动检出提交并克隆存储库,然后根据您的代码安装依赖项、运行检查、构建项目和/或部署 Worker。
本指南在名为 CIWorkflow 的 Workflow 类中定义这些 CI 步骤。要在每次推送后自动启动此 Workflow,请在 Wrangler 配置中添加 cf.artifacts.repo.pushed 触发器。您还应包含:
- R2 绑定(binding):用于存储缓存依赖项快照的存储桶
- Container(以及 Durable Object)绑定(binding):创建指向您容器的绑定,以便在每个
runner()步骤中访问沙箱 - Workflows 绑定(binding)
- Artifacts 绑定(binding)
- 可观测性(可选):通过 Workers 可观测性将 CI 作业作为 Workflow 实例进行检查
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "<worker-name>",
"main": "src/index.ts",
"upload_source_maps": true,
"compatibility_date": "2026-06-16",
"compatibility_flags": ["nodejs_compat"],
"artifacts": [
{
"binding": "ARTIFACTS",
"namespace": "<artifacts-namespace>"
}
],
"containers": [
{
"class_name": "CiSandbox",
"image": "./Dockerfile",
"max_instances": 10,
"instance_type": "standard-4"
}
],
"durable_objects": {
"bindings": [
{
"name": "SANDBOX",
"class_name": "CiSandbox"
}
]
},
"workflows": [
{
"name": "<workflow-name>",
"binding": "CI_WORKFLOW",
"class_name": "CI"
}
],
"exports": {
"CiSandbox": {
"type": "durable-object",
"storage": "sqlite"
}
},
"r2_buckets": [
{
"binding": "BACKUP_BUCKET",
"bucket_name": "<backup-bucket-name>"
}
],
"triggers": {
"events": [
{
"type": "cf.artifacts.repo.pushed",
// filter is optional. If you don't set repo_name, the same Workflow runs for every push to any repo in your Artifacts namespace
"filter": {
"namespace": "CI",
"repo_name": "my-repo"
},
"targets": [
{
"type": "workflow",
"workflow_name": "<workflow-name>"
}
]
}
]
},
"observability": {
"enabled": true,
"logs": {
"enabled": true
}
}
}"$schema" = "node_modules/wrangler/config-schema.json"
name = "<worker-name>"
main = "src/index.ts"
upload_source_maps = true
compatibility_date = "2026-06-16"
compatibility_flags = [ "nodejs_compat" ]
[[artifacts]]
binding = "ARTIFACTS"
namespace = "<artifacts-namespace>"
[[containers]]
class_name = "CiSandbox"
image = "./Dockerfile"
max_instances = 10
instance_type = "standard-4"
[[durable_objects.bindings]]
name = "SANDBOX"
class_name = "CiSandbox"
[[workflows]]
name = "<workflow-name>"
binding = "CI_WORKFLOW"
class_name = "CI"
[exports.CiSandbox]
type = "durable-object"
storage = "sqlite"
[[r2_buckets]]
binding = "BACKUP_BUCKET"
bucket_name = "<backup-bucket-name>"
[[triggers.events]]
type = "cf.artifacts.repo.pushed"
[triggers.events.filter]
namespace = "CI"
repo_name = "my-repo"
[[triggers.events.targets]]
type = "workflow"
workflow_name = "<workflow-name>"
[observability]
enabled = true
[observability.logs]
enabled = trueWrangler 配置中的 [observability] 设置会记录每次流水线运行的状态和日志。要确定哪个阶段失败,请在 Workflows 仪表板中检查该实例:
每个 runner 都会显示自己的输入、输出和状态,因此您可以定位失败的命令。当 runner 失败时,Workflow 会记录其输出,并且不会启动需要其文件的后续阶段。
要部署 Worker,请将 wrangler deploy 传给最后的 runner() 步骤,例如 workspace.runner({ name: "deploy", command: "wrangler deploy" })。
要部署 User Worker,请将 wrangler deploy --dispatch_namespace <DISPATCH_NAMESPACE> 传给最后的 runner() 步骤。
trigger 中的 filter 是可选的。设置 repo_name 后,只有推送到该特定 repo 才会启动 Workflow。省略 repo_name 后,Cloudflare 会为推送到 Artifacts namespace 中任意 repo 的每次操作运行同一个 Workflow。
这对于编写并拥有单一 CI Workflow、并希望将其统一应用于命名空间中每个客户存储库的平台很有用。无需为每个存储库维护单独的触发器,一个共享 Workflow 即可在推送时构建、检查并部署每个存储库。
要为 namespace 中的每个 repo 运行同一个 Workflow,请从 trigger 的 filter 中移除 repo_name,只保留 namespace:
{
"triggers": {
"events": [
{
"type": "cf.artifacts.repo.pushed",
"filter": {
"namespace": "CI"
},
"targets": [
{
"type": "workflow",
"workflow_name": "ci-workflow"
}
]
}
]
}
}[[triggers.events]]
type = "cf.artifacts.repo.pushed"
[triggers.events.filter]
namespace = "CI"
[[triggers.events.targets]]
type = "workflow"
workflow_name = "ci-workflow"每次推送仍会为发生变更的存储库、分支和提交启动各自的 Workflow 实例,因此您可以从同一份共享 Workflow 定义中为每个存储库部署单独的 Worker。