Cloudflare Artifacts Tutorial: Build a Git Repository Worker
Learn how to use Cloudflare Artifacts with a Worker, create Git repositories programmatically, push commits, manage tokens, and connect repositories to web deployments.
On this page
Cloudflare Artifacts moved into open beta on October 1, 2026, giving Workers a Git-compatible place to create, store, fork, inspect, and version application code. Unlike ordinary object storage, an Artifacts repository has Git history and can be connected to standard Git clients, while a Worker can manage repositories through an ARTIFACTS binding. This Cloudflare Artifacts tutorial builds a small TypeScript Worker that creates a repository, returns its Git credentials, and lets you push a real commit into it.Ā
What Cloudflare Artifacts gives a Worker
Artifacts is designed for versioned files and projects rather than individual unstructured objects. A Worker can create a repository for a project, user, session, or task and then use the repository as a programmable Git-backed workspace. That is particularly useful for web platforms that generate projects dynamically, because each generated project can have its own repository instead of sharing one filesystem or manually managing archives. Cloudflare also supports connecting Artifacts repositories to Workers Builds, so a push can lead to a Worker deployment or a preview for another branch.Ā
The important distinction is that the Worker binding manages repository operations, while ordinary Git handles file changes and commits. The binding can create and inspect repositories, create tokens, fork repositories, read commit information, and perform other repository-level operations. For actual Git file operations from a Worker, Cloudflare documents integrations such as isomorphic-git, because a Worker does not provide the normal local Git executable and filesystem environment available on a developer's computer.Ā
Prepare the Worker project before adding Artifacts
You need a Cloudflare account with access to Artifacts, Node.js, Wrangler, and a local Git client for this tutorial. The simplest starting point is a new Worker created with Cloudflare's create-cloudflare command-line tool, commonly called C3. Cloudflare's current Workers documentation requires Node.js and uses C3 to scaffold a Worker project, while the Artifacts guide adds the repository binding afterward.Ā
npm create cloudflare@latest -- artifacts-worker
cd artifacts-worker
When C3 asks what to create, choose the Hello World example, select a Worker-only project, choose TypeScript, and enable Git version control. You can leave deployment disabled for now because the first part of the tutorial runs the Worker locally. The result should be a normal Worker project containing the source file and Wrangler configuration that you will modify in the next step.
Add the Artifacts binding to Wrangler
Open the project's Wrangler configuration and add an artifacts section. The binding name is the identifier your Worker code will use, while namespace identifies the Artifacts namespace containing the repositories. In this example the namespace is called default, but a production application should choose its namespace structure deliberately rather than putting unrelated projects into one shared namespace.Ā
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "artifacts-worker",
"main": "src/index.ts",
"compatibility_date": "2026-10-02",
"artifacts": [
{
"binding": "ARTIFACTS",
"namespace": "default"
}
]
}
The configuration exposes the repository service as env.ARTIFACTS inside the Worker. If you use TypeScript, regenerate the Worker types after adding the binding. Cloudflare's current binding documentation also requires Wrangler 4.145.0 or later for the current Artifacts binding types and certain remote-binding methods, so updating Wrangler before generating types avoids testing against an older binding definition.Ā
npm install --save-dev wrangler@latest
npx wrangler types
After that command completes, Wrangler generates an Artifacts type in the Worker configuration declarations. The useful checkpoint is that your project recognizes ARTIFACTS as part of the Worker environment rather than treating it as an unknown property.
Create the Worker endpoint that creates a repository
Now replace the starter Worker with a small endpoint that creates an Artifacts repository. The binding's create() method returns repository metadata including the repository name, Git remote, default branch, and an initial token. The token is sensitive because it can be used for Git operations, so this tutorial returns it only to demonstrate the complete local flow; a real application should authenticate the caller and avoid exposing repository credentials to unauthorised users.
interface Env {
ARTIFACTS: Artifacts;
}
export default {
async fetch(request: Request, env: Env): Promise {
const url = new URL(request.url);
if (request.method === "POST" && url.pathname === "/repos") {
const created = await env.ARTIFACTS.create("starter-repo");
return Response.json({
name: created.name,
remote: created.remote,
token: created.token
});
}
return Response.json(
{ message: "Use POST /repos to create the repository." },
{ status: 404 }
);
}
};
There is one deliberate limitation in this example: the repository name is fixed. That keeps the first test predictable, but an application that creates repositories for users or tasks should derive a valid unique name and validate the requested name before calling create(). Cloudflare's binding also supports options such as a description, read-only mode, and a chosen default branch when creating a repository.Ā
Start the Worker and create your first repository
Authenticate Wrangler if you have not already done so, then start the local development server. The local Worker exposes the Artifacts binding and gives you an HTTP endpoint that can create the repository. Keep the development server running while you use a second terminal to send the request.Ā
npx wrangler login
npx wrangler dev
Open another terminal and send a POST request to the local endpoint.
curl http://localhost:8787/repos ^
--header "Content-Type: application/json" ^
--data "{\"name\":\"starter-repo\"}"
On macOS or Linux, use the equivalent shell quoting for the JSON body. The exact request format is less important than the result: the Worker should call env.ARTIFACTS.create() and return a repository name, a Git remote, and a temporary token. Cloudflare's own Worker guide uses this same basic sequence to create a repository and obtain the values needed for Git operations.Ā
Use the returned token for the first Git push
At this point the repository exists, but it is empty. Artifacts is Git-compatible, so you can use an ordinary Git client to initialise a local project and push a commit into the repository. The returned credential is intended for Git operations, and Cloudflare recommends passing it through an HTTP authorization header rather than placing the secret directly into persistent Git configuration.Ā
Create a separate directory for the demonstration project and initialise Git there.
mkdir artifacts-demo
cd artifacts-demo
git init -b main
printf '# Artifacts demo\n' > README.md
git add README.md
git commit -m "Initial commit"
Store the remote and token returned by the Worker in shell variables, then add the remote to the local repository. Do not paste a real token into source code, a configuration file committed to Git, or a public issue. The token is a credential for the repository, so treating it like ordinary application data defeats the access control that Artifacts provides.
export ARTIFACTS_REMOTE="PASTE_REMOTE_FROM_RESPONSE"
export ARTIFACTS_TOKEN="PASTE_TOKEN_FROM_RESPONSE"
git remote add origin "$ARTIFACTS_REMOTE"
git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" push -u origin main
On Windows PowerShell, set the two environment variables using PowerShell syntax and use the same Git authorization-header technique. A successful push means the local commit has crossed the boundary from your machine into the Cloudflare-managed repository. Cloudflare's documentation specifically recommends the http.extraHeader approach because it keeps the token out of the repository's Git configuration.Ā
Verify the commit with a second Git clone
The easiest way to prove that the repository contains a real Git commit is to clone it into another directory. This separates the original local repository from the copy you are using to verify the remote, so a successful result cannot be explained simply by Git reading the original working tree. Use the same short-lived authorization header when cloning.Ā
cd ..
git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" \
clone "$ARTIFACTS_REMOTE" artifacts-clone
git -C artifacts-clone log --oneline -1
The final command should display the initial commit you pushed. That is the point at which the basic integration has been verified: the Worker created the repository, Git authenticated against the returned remote, the commit was pushed, and another Git client could retrieve the history. If the clone fails, check the token value and expiration first because Artifacts repository tokens are scoped credentials rather than permanent passwords.Ā
Use short-lived repository tokens instead of permanent access
For an application that creates repositories dynamically, returning the original creation token to every caller is not a good access model. Artifacts exposes repository-level token management, including creating tokens with a scope and time-to-live, listing tokens, and revoking them. The binding documentation shows that a Worker can obtain a repository handle with env.ARTIFACTS.get() and create a scoped token for a specific operation.Ā
const repo = await env.ARTIFACTS.get("starter-repo");
const token = await repo.createToken("read", 3600);
In this example the token is limited to read access and has a time-to-live of 3,600 seconds, which is one hour. That is a much better pattern for a service that needs to let a temporary process inspect a repository without handing it long-lived write capability. For write operations, use the narrowest scope required by the job and revoke credentials when the workflow no longer needs them. The exact permission model should be tested against the current Artifacts API because the product is still in beta.Ā
Connect Artifacts to a real web deployment
The basic repository integration becomes more interesting when the repository itself becomes the source for a web application's deployment. Cloudflare Workers Builds can connect an Artifacts repository, build the project when commits arrive, deploy changes from the production branch, and create or update Worker Previews for other branches. That means a web platform can use Artifacts as the versioned project store and Workers as the runtime without maintaining a separate Git hosting service for that workflow.Ā
This pattern is particularly useful for applications that generate or customise websites for users. A platform could create an isolated repository for a project, write the generated application into it, commit the result, and let the deployment system build that revision. Artifacts also supports repository events, so pushes, forks, imports, and other repository changes can become triggers for further automation. The architectural benefit is that the repository becomes an active part of the application rather than merely a place where developers manually store source code.Ā
For automated build pipelines, Cloudflare also documents an event-driven path in which an Artifacts push starts a Workflow that can run checks such as linting, type checking, formatting, and tests before deployment. That separates repository storage from the build process: Artifacts records what changed, while the CI workflow decides whether the revision is safe to ship.Ā
Know where the Worker binding stops
One easy mistake is to assume that env.ARTIFACTS behaves like a complete filesystem. It does not. The binding gives the Worker repository-level capabilities and Git-related metadata, but Cloudflare's documentation explains that reading and writing the actual file tree from a Worker requires Git operations or an additional integration such as isomorphic-git. That distinction matters when designing an application that generates source code, because repository creation and file manipulation are separate pieces of the architecture.Ā
For example, a Worker that only needs to create an isolated repository can use the binding directly. A Worker that needs to generate a complete React project, commit several files, and push them needs a Git-capable approach as well. Cloudflare's isomorphic-git example demonstrates this model by combining the Artifacts binding with an in-memory filesystem so Git operations can run inside the Worker environment. In production, the write-capable route must also authenticate its caller rather than exposing repository creation or token issuance to an unauthorised HTTP request.Ā
The first Artifacts project should therefore stay small: create one repository, push one commit, clone it somewhere else, and only then add automated generation or deployment. Once that path is reliable, the same primitives can support isolated repositories for user projects, agent sessions, previews, or generated web applications. Cloudflare's open beta makes those patterns available now, but the sensible approach is to keep repository permissions narrow and treat the API as an evolving platform while the beta continues.Ā
Share this post
Written by



