Version agent work with Cloudflare Artifacts

Preserve the version behind an agent's result

Two agents improve a learning app at the same time. One changes the headings; the other fixes input validation. Both return files and say the checks passed. To compare their work, you need the starting version, each change, and the exact version each check inspected. A final directory and a green badge cannot answer those questions by themselves.

Artifacts supplies programmable Git storage for these work units. Your application supplies the ownership ledger and the decision to accept a change. Keep four identifiers together: task, baseline commit, candidate commit, and validation result. This article proposes that design; it does not describe a deployed Kumyu pipeline.

Scope checked October 4, 2026: the October 1 announcement identifies Artifacts as open beta, available on Workers Paid. Account eligibility, real isolation tests, throughput, and cost have not been tested here. All exercises below are not run. Documentation publication dates are unknown; revision dates are retained in the research record separately from this verification day.

Give each store one responsibility

What you need to retain	Suggested owner	Why it belongs there
Source files, diffs, and commit history	Artifacts repository	Compare and recover a version of the work.
Task owner, permission decisions, validation status	Application ledger, such as a Durable Object	Decide who may create, inspect, accept, or delete work.
A multi-step validation process	Workflow, when needed	Track independent checks and explicit failures.
Large videos, logs, or build outputs	R2 or another chosen object store	Give bulky outputs their own retention policy.
Commit-to-output relationship	Small application-defined manifest	Bind an output reference and hash to the checked commit.

This separation is an original design recommendation. Git storage does not establish a review policy, execute generated code, or prove that a result is safe. Runtime recovery is a different question, covered in the sandbox state article.

Scroll horizontally to read the diagram.

Original Kumyu diagram, based on the official repository, event, and CI contracts. Read it in order: 1 record a baseline; 2 allocate task repositories and scoped credentials; 3 receive a push revision; 4 check that revision; 5 retain large outputs separately; 6 compare candidates using commit-linked evidence. Approval belongs to the application. A dashed boundary denotes that responsibility, rather than an undocumented Artifacts component.

Choose repositories or branches deliberately

A repository has its own history, refs, remote, tokens, and lifecycle inside a namespace. Use separate task repositories when work needs separate credentials and cleanup. Branches in one repository are useful when collaborators share that access boundary; a repository-scoped token should not be described as permission for only one branch.

Record the actual starting commit in the task repository before handing it to the agent. The binding's fork() accepts a target name and options, not a requested commit hash. Do not assume that a moving source branch and a separately recorded baseline were atomically frozen together. Read back the fork's starting version and compare it with the intended baseline; reject or deliberately resolve a mismatch before work begins. That check is an application design, not a claimed consistency guarantee.

The task ledger might contain taskId, ownerId, namespace, repository identity, baseline SHA, candidate SHA, and a validation-record reference. Those are proposed fields, not Artifacts API fields. Keeping them explicit makes “checked A, displayed B” a diagnosable error.

Follow the credential path

The authentication guide separates three interfaces:

Caller and interface	Authentication	Consequence for this design
Trusted Worker, binding	Configured artifacts binding	The Worker calls the bound namespace without passing a runtime API token. Authenticate and authorize the application's incoming task first.
External management client, REST	Cloudflare API token, Artifacts Read or Edit permissions	Keep management credentials away from generated code.
Git client	Repository-scoped Artifacts token, read or write	The agent receives write access only to its task repository; a checker can receive read access.

Git protocol documentation recommends using the returned remote and a Bearer header for local workflows. Keep credentials out of remote URLs, persisted manifests, browser responses, and command traces. A short-lived token still needs a trusted delivery path; expiry is not an ownership check.

The binding reference makes these settings consequential:

Setting or method	Exact meaning	Worked choice and effect
artifacts[].binding, namespace	Maps an environment binding to a namespace	ARTIFACTS and a chosen test namespace keep the intended resource explicit.
get(name)	Returns a disposable repository capability	Use using; call info() for metadata rather than reading assumed properties.
createToken(scope?, ttl?)	Scope defaults to write; TTL is in seconds	Explicit "read", 3600 asks for a one-hour checker credential. The returned fields include plaintext and expiresAt; do not return them to an unauthorised client.

The current reference requires Wrangler 4.145.0 or later for generated binding types and Blob-returning methods with remote local development. These examples have not issued credentials or run an API request. They explain a contract, not a ready-to-deploy handler.

Pin the event's revision before checking it

The push event schema names cf.artifacts.repo.pushed, source namespace and repoName, and payload ref, before, and after. Suppose a push produces commit A, then B arrives while A is being checked. Reading the latest branch at check time can inspect B while recording the result as A. Resolve and check the event's after, then retain the actual checked SHA with every result.

Use the authenticated platform event route configured for your consumer, an allowlist of owned repositories, and strict payload validation. General event subscriptions deliver structured records to Queues; do not invent a generic HTTP webhook signature or expose a route that accepts arbitrary caller-supplied “push” records. If you forward records through your own HTTP integration, its authentication is a separate application responsibility.

For a queue consumer, Queues provides at least once delivery. Define an application validation key from namespace, repository, after, and pipeline version, and persist the transition before repeating work. Include running, passed, and failed outcomes. A key alone cannot make external side effects exactly once; each side effect needs its own retry contract. Do not apply a Queues delivery guarantee to a different event-to-Workflow path without evidence.

Select the smallest CI path that fits

The build guide offers Workers Builds for standard Worker builds and deployment, including previews on other branches. Its custom CI path uses a Workflow for checks, caching, retry settings, and optional delivery. A failed check stops that example before deployment.

For custom triggers, specify triggers.events type cf.artifacts.repo.pushed and filter namespace and repoName: omitting the repository filter broadens the trigger to pushes across the namespace. A binding is resource access; a trigger selects events. Neither substitutes for application ownership validation.

Choose standard builds when their branch and command policy fits. Choose a custom process when you need an approval gate, tenant-specific delivery, or different validation branches. The exercise here ends at reviewable candidates. An automatic production deploy would require a separate release decision tied to the same checked commit.

Size the workspace and its lifetime

The current limits specify 1 GB per repository, 32 MB per file/blob, and 1 TB per account, with an increase request possible for the account limit. Unlimited repository count does not mean unlimited retained data. Keep a small manifest in Git for large external outputs: checked commit, output reference, digest, and check results. Its format is your contract; Artifacts does not validate the relationship for you.

ArtifactFS can mount a working tree while content hydrates on demand. It needs a suitable FUSE host and repo token. This trades complete local availability for earlier access to a large tree; first reads can block. For the small fixture in this article, a regular clone is simpler. No startup-time improvement has been measured here.

Set namespace jurisdiction at creation: eu, us, or omitted for unrestricted storage and processing. It applies to all repositories in that namespace and cannot be changed afterward. It does not determine where your CI runner, model requests, logs, or R2 bucket operate. Trace those paths independently before claiming application-wide residency.

Budget operations and retention separately

The announced price table includes 10,000 monthly operations and 1 GB of storage; overage is USD 0.15 per 1,000 operations and USD 0.50 per GB-month. Storage uses daily peaks averaged over a 30-day billing period across repositories. Repositories remain until explicitly deleted.

The billing start is unresolved as of October 4: the price page says October 14, 2026, while the October 1 blog says October 15. Both dates are future. Recheck before budgeting a live workload; this article does not claim billing has begun.

After billing begins, a hypothetical month with 30,000 operations and 5 GB-month, with those allowances applied, has an Artifacts overage of (30,000 − 10,000) / 1,000 × $0.15 + (5 − 1) × $0.50 = $5.00. This is arithmetic using announced rates, not a measured bill. It excludes the Workers Paid subscription, Worker/Workflow/runner execution, model calls, logs, and other storage.

Define a retention policy such as keep accepted work and required evidence, then expire rejected disposable tasks after their agreed review period. The application must explain and authorize deletion; do not silently delete a user's repository to meet a budget. Revoke no-longer-needed task credentials separately from deciding which history to retain.

Exercise: make three failures visible

This unrun exercise starts offline. Use a non-sensitive fixture with two proposed changes and label two immutable local commits A and B. Create mock event records and a review manifest without tokens, account identifiers, or public deployment. First show that the ledger assigns each check to its real commit. A later live exercise needs an authorised test account, Workers Paid, and a budget; none has been provisioned here.

Case to inject	Required observation	Evidence to retain
Deliver the same A event twice	One logical validation record, with explicit retry state	Validation key and result references.
Deliver B while A is checking	A's result remains attached to A, even if B is now branch head	Event after, checked SHA, and candidate SHA.
Make B's check fail	Failure is visible and B cannot become an accepted candidate	Failed check and unchanged acceptance record.
Use a read token to push, in a later authorised live test	Denial without a token in the log	Redacted permission outcome.

The deliverable is a small review record that lets another person trace candidate → commit → check → output digest. Measure runtime, retry outcomes, and costs only when you actually run the pipeline. Stop a live exercise on unexpected publication, cross-repository access, or credential exposure, and preserve a redacted failure record instead of manufacturing a successful result.