← Artifacts / artifacts / guides

Sestavení a nasazení repozitářů Artifacts

Události Artifacts dokážou sestavit a nasadit projekty uložené v repozitářích Artifacts. Když uživatel nebo agent odešle commit, tato událost spustí Instance Workflow.

V rámci Workflow definujete pipeline pro průběžnou integraci (CI) pomocí @cloudflare/ci SDK k ukládání závislostí do cache, spouštění kontrol a sestavení projektu. Poslední krok CI pipeline může výstup nasadit do Worker nebo Workers for Platforms Uživatelský Worker.

Hodí se to, když potřebujete:

• Automaticky sestavuje a nasazuje kód aplikace uložený v Artifacts.
• Při každém pushi spouštějte linting, kontrolu typů, testy a další kontroly.
• Znovu použijte závislosti, pokud soubor lockfile (tj. pnpm-lock.yaml) se nezměnila.
• Zastavte nasazení, pokud kontrola nebo sestavení selže.
• Omezte přístup tokenu API na krok nasazení.
• Výstup nasaďte do Worker nebo Workers for Platforms Uživatelský Worker.

1. Odesílejte změny repozitáře : git push do repozitáře Artifacts vyvolá artifacts.repo.pushed událost, která identifikuje odeslaný repozitář, větev a commit.
2. Spusťte CI Workflow : Událost spustí Workflow, který provede checkout commitu, nainstaluje a uloží do cache závislosti a paralelně spustí kroky CI (build, lint, typecheck a format). Pokud některý krok selže, Workflow se před nasazením zastaví.
3. Nasazení Workeru : Workflow nasadí sestavený Worker buď přímo do vašeho účtu, nebo jako User Worker, pokud používáte Workers for Platforms

Použijte @cloudflare/ci SDK k definování kroků CI. SDK poskytuje dva nástroje, které vám pomohou pipeline sestavit:

• Runnery : každé runner() volání spustí izolovaný sandbox a provede shellový příkaz. Používáte stejné příkazy, jaké už spouštíte lokálně nebo v jiném CI systému. Každý runner zaznamenává vlastní protokoly, stav a výstupní soubory.
• Cache , cache možnost u runneru ukládá nainstalované závislosti do cache, takže je pozdější běhy nemusí znovu instalovat. Předejte soubory, které závislosti určují, například pnpm-lock.yaml, do cache.inputs. Pokud se tyto soubory nezměnily, SDK obnoví výsledek uložený v cache místo opětovného spuštění příkazu.

Runner s mezipamětí použije snímek svého sandboxu, který pak znovu využijí další runnery. Z jednoho výsledku uloženého v cache může vycházet více runnerů: runnery pro lint, kontrolu typů i testy mohou sdílet jednu uloženou instalaci.

Runner, který selže, opakuje pokus podle svého konfigurace kroku, kde můžete definovat počet pokusů o opakování, plán backoffu a časové limity. Runnery, které závisí na předchozím kroku, se nespustí, dokud se opakování tohoto kroku úspěšně nedokončí. Pokud je dosažen nastavený limit opakování, Workflow skončí ve stavu Errored stav.

Zde je příklad, jak nastavit Workflow tak, aby pomocí runnerů a cache instaloval závislosti, spouštěl kontroly, sestavil projekt a nasadil 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,
			},
		});
	}
}

Když uživatel nebo agent pushne commit do repozitáře Artifacts, Artifacts vygeneruje událost, která identifikuje repozitář, větev a commit, jenž se změnil. Tuto událost pak použijete ke spuštění instance Workflow, která spustí CI pipeline: automaticky checkoutne commit a naklonuje repozitář, poté nainstaluje závislosti, spustí kontroly, sestaví projekt a/nebo nasadí Worker podle vašeho kódu.

Tento návod definuje tyto kroky CI ve třídě Workflow s názvem CIWorkflow. Chcete-li tento Workflow spouštět automaticky po každém push, přidejte cf.artifacts.repo.pushed trigger do konfigurace Wrangler. Měli byste také zahrnout:

• Vazba R2: bucket, ve kterém bude uložen snímek vašich závislostí uložených v mezipaměti
• Binding kontejneru (a Durable Object): vytvořte binding ke svému kontejneru pro přístup k sandboxům během každého runner() krok
• Workflows binding
• Binding Artifacts
• Observabilita (volitelné): kontrolujte úlohy CI jako instanci Workflow pomocí Pozorovatelnost Workers

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "<worker-name>",
  "main": "src/index.ts",
  "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 repoName we will run the same workflow for every push on any repo in your Artifacts namespace
        "filter": {
          "namespace": "CI",
          "repoName": "my-repo"
        },
        "target": {
          "scriptName": "<worker-name>",
          "workflowName": "<workflow-name>"
        }
      }
    ]
  },
  "observability": {
    "enabled": true,
    "logs": {
      "enabled": true
    }
  }
}

"$schema" = "node_modules/wrangler/config-schema.json"
name = "<worker-name>"
main = "src/index.ts"
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"
  repoName = "my-repo"

  [triggers.events.target]
  scriptName = "<worker-name>"
  workflowName = "<workflow-name>"

[observability]
enabled = true

  [observability.logs]
  enabled = true

[observability] nastavení ve vaší konfiguraci Wrangleru zaznamenává stav a protokoly každého běhu pipeline. Pokud chcete zjistit, která fáze selhala, zkontrolujte instanci v dashboardu Workflows:

Každý runner zobrazuje svůj vlastní vstup, výstup a stav, takže můžete identifikovat příkaz, který selhal. Když runner selže, Workflow zaznamená jeho výstup a nespustí kroky, které potřebují jeho soubory.

Chcete-li nasadit Worker, předejte wrangler deploy do vašeho finálního runner() krok, tedy workspace.runner({ name: "deploy", command: "wrangler deploy" }).

Chcete-li nasadit User Worker, předejte wrangler deploy --dispatch_namespace <DISPATCH_NAMESPACE> do vašeho finálního runner() krok.

filter ve vašem triggeru je volitelný. Když nastavíte repoName, Workflow spustí pouze push do tohoto konkrétního repozitáře. Pokud vynecháte repoName, Cloudflare spustí stejný Workflow při každém push do jakéhokoli repozitáře ve vašem namespace Artifacts.

Hodí se to pro platformy, které vytvářejí a spravují jeden CI Workflow a chtějí ho jednotně použít pro každý zákaznický repozitář v daném namespace. Místo udržování samostatného triggeru pro každý repozitář sestavuje, kontroluje a nasazuje každý repozitář při push jeden sdílený Workflow.

Chcete-li spustit stejný Workflow pro každý repozitář v namespace, vložte repoName z triggeru filter a zachovejte pouze namespace:

{
	"triggers": {
		"events": [
			{
				"type": "cf.artifacts.repo.pushed",
				"filter": {
					"namespace": "CI"
				},
				"target": {
					"scriptName": "my-ci-worker",
					"workflowName": "ci-workflow"
				}
			}
		]
	}
}

[[triggers.events]]
type = "cf.artifacts.repo.pushed"

  [triggers.events.filter]
  namespace = "CI"

  [triggers.events.target]
  scriptName = "my-ci-worker"
  workflowName = "ci-workflow"

Každý push i tak spustí vlastní instanci Workflow pro repozitář, větev a commit, které se změnily, takže můžete ze stejné sdílené definice Workflow nasadit samostatný Worker pro každý repozitář.