--- title: "Cloudflare Artifacts" description: "Read repositories, files, trees and commits from Cloudflare Artifacts, the Git storage built for agents." canonical_url: "https://forges.link/providers/cloudflare-artifacts" --- # Cloudflare Artifacts > Read repositories, files, trees and commits from Cloudflare Artifacts, the Git storage built for agents. The Cloudflare Artifacts provider works with [Cloudflare Artifacts](https://developers.cloudflare.com/artifacts/), Git storage that Cloudflare built for agents. It reads repositories and their contents: files, trees, the commit log and single commits. Artifacts stores Git repositories only, with no issues or pull requests. The [REST API documentation](https://developers.cloudflare.com/artifacts/api/rest-api/) covers the endpoints.
Detail Value
Import forges/cloudflare-artifacts
Factories cloudflareArtifacts()
Auth token
The Cloudflare Artifacts provider is experimental, because Artifacts is in open beta and its API can still change. To learn what that means, see [Capabilities](https://forges.link/concepts/capabilities). ## Authentication The provider takes a Cloudflare API token with the **Artifacts** > **Read** permission. It also needs the id of the account that holds the repositories. It sends the token in an `Authorization: Bearer ` header: ```ts import { cloudflareArtifacts } from 'forges/cloudflare-artifacts' const forge = cloudflareArtifacts({ accountId: process.env.CLOUDFLARE_ARTIFACTS_ACCOUNT_ID!, auth: { type: 'token', token: process.env.CLOUDFLARE_ARTIFACTS_TOKEN! }, }).create() ``` There are no anonymous reads. Even cloning needs a token, so every repository reports `visibility: 'private'`. The repository tokens that Artifacts hands out for `git clone` and `git push` don't work here. Those open the Git remote, not the REST API. ## Refs A namespace is the owner, so `forges-fixtures/forges` is the repository `forges` in the namespace `forges-fixtures`. The instance is the host of the account's Git remotes, `.artifacts.cloudflare.net`. Two accounts give two instances, so one `createForges()` can hold both without mixing up their refs. Artifacts has no website, so `urlFor()` and `parseUrl()` return `undefined`. ## Repositories `repos.list()` walks the namespaces of the account one at a time. A page only holds repositories of one namespace. `repos.byOwner()` lists a single namespace. Both pass `sort` and `direction` on to Artifacts. Every repository belongs to the account, so an `affiliation` filter without `'owner'` lists nothing. A fork names its parent, which becomes `Repo.parent`. An imported repository isn't a fork, even though Artifacts records the remote it came from. ## Contents The provider resolves a branch or tag to a commit through the commit log. `contents.tree()` resolves its ref this way first. Without a `ref`, `contents.file()` and `contents.tree()` read the head of the default branch. The log accepts only branch and tag names, so the provider translates `HEAD` and full ref names such as `refs/heads/main`. An abbreviated sha returns no commits, so the provider rejects it with `NotFoundError`. `contents.tree()` reads one level. With `recursive`, it still returns one level, with a `recursive_unsupported` warning. `contents.commits()` pages through the log by offset. The log has no filters, so `path`, `author`, `since` and `until` are ignored with a `filter_unsupported` warning. Artifacts has no diff endpoint. So `contents.commit()` compares the commit's tree with the tree of its first parent, and reads only the directories that changed. A small commit costs a few requests. A commit that touches hundreds of directories costs hundreds. The comparison finds a rename only when the file moved without an edit. Git would call an edited rename `renamed` too, but here it's a `removed` file and an `added` one. A file whose mode alone changed comes back as `changed`. The files don't carry line counts either. A shallow import leaves out the parents past its depth, and for the oldest commits `files` is then `undefined`. There are no endpoints for branches, tags or comparing two refs, so those operations are unsupported. ## Events Artifacts sends no webhooks. It publishes [events](https://developers.cloudflare.com/artifacts/guides/event-subscriptions/) to Cloudflare Queues, which the provider doesn't read, so `capabilities.sources.webhook` is `false`. There's no `cloudflareArtifactsLite()` factory either, because `cloudflareArtifacts()` contains no webhook code. ## Capabilities
Capability Support Without credentials
experimental ✅ ✅
sources.poll ❌ ❌
sources.webhook ❌ ❌
sources.subscribe ❌ ❌
repos.get ✅ ❌
users.get ❌ ❌
users.me ❌ ❌
users.sponsorable ❌ ❌
users.events ❌ ❌
repos.list ✅ ❌
repos.byOwner ✅ ❌
repos.labels ❌ ❌
repos.createLabel ❌ ❌
repos.milestones ❌ ❌
repos.collaborators ❌ ❌
repos.contributors ❌ ❌
repos.contributorStats ❌ ❌
repos.templates ❌ ❌
repos.permissionFor ❌ ❌
repos.addCollaborator ❌ ❌
repos.assignableUsers ❌ ❌
repos.reviewerCandidates ❌ ❌
repos.events ❌ ❌
orgs.teams ❌ ❌
orgs.teamMembers ❌ ❌
threads.get ❌ ❌
threads.list ❌ ❌
threads.getMany ❌ ❌
threads.events ❌ ❌
comments.list ❌ ❌
comments.get ❌ ❌
comments.edit ❌ ❌
comments.delete ❌ ❌
reactions.list ❌ ❌
notifications.list ❌ ❌
notifications.markRead ❌ ❌
notifications.markDone ❌ ❌
notifications.unsubscribe ❌ ❌
notifications.markAllRead ❌ ❌
notifications.markAllDone ❌ ❌
notifications.unreadCount ❌ ❌
writes.comment ❌ ❌
writes.upsertComment ❌ ❌
writes.close ❌ ❌
writes.reopen ❌ ❌
writes.create ❌ ❌
writes.update ❌ ❌
writes.setLabels ❌ ❌
writes.addLabels ❌ ❌
writes.removeLabels ❌ ❌
writes.setMilestone ❌ ❌
writes.react ❌ ❌
writes.setAssignees ❌ ❌
writes.requestReview ❌ ❌
writes.merge ❌ ❌
writes.approveAndMerge ❌ ❌
writes.transfer ❌ ❌
writes.markDuplicate ❌ ❌
subscriptions.get ❌ ❌
subscriptions.set ❌ ❌
installations ❌ ❌
checks.thread ❌ ❌
checks.list ❌ ❌
checks.get ❌ ❌
checks.report ❌ ❌
checks.rerun ❌ ❌
ci.runs ❌ ❌
ci.run ❌ ❌
ci.jobs ❌ ❌
ci.job ❌ ❌
ci.log ❌ ❌
contents.file ✅ ❌
contents.tree ✅ ❌
contents.branches ❌ ❌
contents.tags ❌ ❌
contents.resolveRef ✅ ❌
contents.commits ✅ ❌
contents.commit ✅ ❌
contents.compare ❌ ❌
contents.commitFiles ❌ ❌
contents.threadFiles ❌ ❌
contents.threadCommits ❌ ❌
reviews.list ❌ ❌
reviews.get ❌ ❌
reviews.create ❌ ❌
reviews.submit ❌ ❌
reviews.approve ❌ ❌
reviews.reply ❌ ❌
reviews.resolveThread ❌ ❌
releases.list ❌ ❌
releases.get ❌ ❌
releases.latest ❌ ❌
releases.getByTag ❌ ❌
releases.downloadAsset ❌ ❌
releases.create ❌ ❌
releases.update ❌ ❌
webhooks.list ❌ ❌
webhooks.create ❌ ❌
webhooks.update ❌ ❌
webhooks.delete ❌ ❌
webhooks.rotateSecret ❌ ❌
webhooks.deliveries ❌ ❌
webhooks.redeliver ❌ ❌
search.threads ❌ ❌
search.repos ❌ ❌
search.commits ❌ ❌
search.code ❌ ❌
securityAlerts ❌ ❌
eventKinds native native
authKinds token token
limits unknown unknown
## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.