Repositories
Artifacts stores work in repositories. A repository is one isolated Git service with its own history, refs, remote URL, tokens, and durable state.
Every repository lives inside one namespace. If the namespace does not exist yet, Artifacts creates it when you create the first repo in it.
The namespace groups related repositories, and the repository name identifies one repository inside that group.
A repository has three identifiers:
- a namespace name
- a repository name
- a repository ID returned by the APIs
The namespace and repository name form the stable address that you use in the Workers binding, the REST API, and the Git remote. The repository ID is useful when you need an opaque identifier in API responses or logs.
Each repository is isolated from other repositories. Tokens, lifecycle, refs, and mutations apply to that repository only.
Artifacts exposes the same repository through three interfaces:
| Interface | What you use it for | What it returns |
|---|---|---|
| Workers binding | Create, list, import, inspect, fork, delete, and mint tokens from a Worker | Repository metadata, repository handles, and repo-scoped token results |
| REST API | Create, list, import, inspect, fork, delete, and mint tokens from external systems | Cloudflare API responses with repository metadata and token results |
| Git protocol | Clone, fetch, pull, and push repository contents | Standard Git behavior over HTTPS |
These interfaces point to the same repository.
For example, you can create a repository from the Workers binding or the REST API, then hand the returned remote URL to a standard Git client. You do not create different repositories for each interface.
The Workers binding and the REST API are control-plane interfaces. Use them to manage repositories and tokens.
The Git protocol is the data-plane interface. Use it to read and write commits, trees, and refs through a normal Git workflow.
That split leads to a common pattern:
- Use the Workers binding or REST API to create a repository.
- Read back the repository
remoteURL. - Mint a repo-scoped token.
- Use the
remoteand token withgit clone,git fetch,git pull, orgit push.
Repository scope matters in two places: naming and access.
Repository names are unique within a namespace, not across your whole account. You can reuse a short repository name in different namespaces when that helps your environment or tenant layout.
For example, a repository named app can exist in both the prod namespace and the staging namespace.
Artifacts tokens are repo-scoped. A token minted for one repository does not grant access to another repository, even when both repositories live in the same namespace.
Use read tokens for clone, fetch, and pull. Use write tokens only when a client must push changes.
Artifacts works best when you treat each repository as one unit of work.
Use one repository per agent, session, user task, baseline, or fork target when those units need separate history, cleanup, and access control. Use namespaces to group those repositories by environment, tenant, or shard.
For more information, refer to Namespaces, How Artifacts works, and Best practices for Artifacts.