Draft
Conversation
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Contributor
elithrar
force-pushed
the
silverlock/project-hail-mary-was-great
branch
from
b51ee38 to
740c888
Compare
elithrar
force-pushed
the
silverlock/project-hail-mary-was-great
branch
from
3e4a619 to
02dc697
Compare
elithrar
changed the title
elithrar
changed the title
|
|
||
| :::note | ||
|
|
||
| Artifacts in currently in private beta. Read the [announcement blog](https://blog.cloudflare.com/artifacts-git-for-agents-beta) to learn more about how Artifacts works. |
Contributor
There was a problem hiding this comment.
Suggested change
| Artifacts in currently in private beta. Read the [announcement blog](https://blog.cloudflare.com/artifacts-git-for-agents-beta) to learn more about how Artifacts works. | |
| Artifacts is currently in private beta. Read the [announcement blog](https://blog.cloudflare.com/artifacts-git-for-agents-beta) to learn more about how Artifacts works. |
Contributor
There was a problem hiding this comment.
a bit weird to have "go read the blog instead of the docs to learn more about how it works"
Comment on lines
+32
to
+35
| - store versioned file trees instead of raw blobs | ||
| - hand off work to Git-aware tools, agents, and automation | ||
| - isolate work in separate repos or branches for safer parallel execution | ||
| - fork from a shared baseline and diff or merge the results later |
Contributor
There was a problem hiding this comment.
Suggested change
| - store versioned file trees instead of raw blobs | |
| - hand off work to Git-aware tools, agents, and automation | |
| - isolate work in separate repos or branches for safer parallel execution | |
| - fork from a shared baseline and diff or merge the results later | |
| - Store versioned file trees instead of raw blobs | |
| - Hand off work to Git-aware tools, agents, and automation | |
| - Isolate work in separate repos or branches for safer parallel execution | |
| - Fork from a shared baseline and diff or merge the results later |
| - isolate work in separate repos or branches for safer parallel execution | ||
| - fork from a shared baseline and diff or merge the results later | ||
|
|
||
| Artifacts stores versioned file trees behind a Git-compatible interface, so the same repository can be addressed from [Workers](/workers/), the REST API, and Git clients. Agents already know Git, which means you can give an agent a repository URL, let it work independently, and have it commit its output back to Artifacts with the same tools it already uses elsewhere. You can create one repo per agent, per user, per branch, or per task, scale that pattern to millions of repositories, and keep each unit of work separate until you are ready to compare or merge changes. |
Contributor
There was a problem hiding this comment.
As someone who is fresh to artifacts, I would benefit from a code snippet to understand:
- Can i create a 'git repo' via sdk? This is programmatic Git repo creation to give to agents?
- How do I interact with it? you can use
git cliin a sandbox? what is the api from a worker?
| order: 1 | ||
| --- | ||
|
|
||
| Use this pattern when you want to discover a repo over the REST API and then hand the returned HTTPS remote to a standard git client. |
Contributor
There was a problem hiding this comment.
Suggested change
| Use this pattern when you want to discover a repo over the REST API and then hand the returned HTTPS remote to a standard git client. | |
| Use this pattern when you want to discover a repo over the REST API and then hand the returned HTTPS remote to a standard Git client. |
| Steps, | ||
| } from "~/components"; | ||
|
|
||
| Create an Artifacts repo from a Worker and use a standard git client to push and pull content. |
Contributor
There was a problem hiding this comment.
Suggested change
| Create an Artifacts repo from a Worker and use a standard git client to push and pull content. | |
| Create an Artifacts repo from a Worker and use a standard Git client to push and pull content. |
| }; | ||
| const repoName = body.name ?? "starter-repo"; | ||
|
|
||
| // Create the repo and return the remote plus initial write token. |
Contributor
There was a problem hiding this comment.
Suggested change
| // Create the repo and return the remote plus initial write token. | |
| // Create the repo and return the remote URL plus initial write token. |
|
|
||
| </TypeScriptExample> | ||
|
|
||
| This Worker does one job: create an Artifacts repo and return the values your git client needs next. |
Contributor
There was a problem hiding this comment.
Suggested change
| This Worker does one job: create an Artifacts repo and return the values your git client needs next. | |
| This Worker does one job: create an Artifacts repo and return the values your Git client needs next. |
|
|
||
| This Worker does one job: create an Artifacts repo and return the values your git client needs next. | ||
|
|
||
| ## 4. Create a repo through your Worker |
Contributor
There was a problem hiding this comment.
Suggested change
| ## 4. Create a repo through your Worker | |
| ## 4. Invoke your Worker to create a repo |
| git push -u origin main | ||
| ``` | ||
|
|
||
| This uses the recommended HTTPS remote form. The `x` username is ignored, and the token secret is used as the Basic auth password. |
Contributor
There was a problem hiding this comment.
Suggested change
| This uses the recommended HTTPS remote form. The `x` username is ignored, and the token secret is used as the Basic auth password. | |
| This uses the recommended HTTPS remote form. The `x` username from the `ARTIFACTS_AUTH_REMOTE` is ignored, and the token secret is used as the Basic auth password. |
| curl "https://api.cloudflare.com/client/v4/accounts/${ARTIFACTS_ACCOUNT_ID}/artifacts/namespaces/starter-namespace/repos" --header "Authorization: Bearer $ARTIFACTS_JWT" --header "Content-Type: application/json" --data '{"name":"starter-repo"}' | ||
| ``` | ||
|
|
||
| Any git client that speaks smart HTTP can use the returned remote URL: |
Contributor
There was a problem hiding this comment.
Suggested change
| Any git client that speaks smart HTTP can use the returned remote URL: | |
| Any Git client that speaks smart HTTP can use the returned remote URL: |
| @@ -0,0 +1,42 @@ | |||
| --- | |||
| title: Git client | |||
| description: Example Artifacts integration with a git client. | |||
Contributor
There was a problem hiding this comment.
Suggested change
| description: Example Artifacts integration with a git client. | |
| description: Example Artifacts integration with a Git client. |
|
|
||
| import { LinkCard } from "~/components"; | ||
|
|
||
| Create an Artifacts repo with the REST API, then use a regular git client to push and pull content. |
Contributor
There was a problem hiding this comment.
Suggested change
| Create an Artifacts repo with the REST API, then use a regular git client to push and pull content. | |
| Create an Artifacts repo with the REST API, then use a regular Git client to push and pull content. |
| git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" push -u origin main | ||
| ``` | ||
|
|
||
| ## 6. Pull the repo with a regular git client |
Contributor
There was a problem hiding this comment.
Suggested change
| ## 6. Pull the repo with a regular git client | |
| ## 6. Pull the repo with a regular Git client |
| order: 1 | ||
| --- | ||
|
|
||
| Artifacts provides a versioned filesystem abstraction for storing and exchanging file trees. |
|
|
||
| Use consistent naming, version promotion, and lifecycle conventions so Artifact producers and consumers can share file trees safely. | ||
|
|
||
| This page will document recommended patterns for structuring repositories, limiting large writes, handling retention, and integrating Artifacts into deployment or agent workflows. |
Comment on lines
+20
to
+22
| Use the Artifacts Workers binding to create, inspect, fork, and delete repos without making raw HTTP calls from your Worker. | ||
|
|
||
| Wrangler exposes Artifacts as a first-class binding and returns repo handles for repo-scoped operations such as token management and forking. |
Contributor
There was a problem hiding this comment.
Suggested change
| Use the Artifacts Workers binding to create, inspect, fork, and delete repos without making raw HTTP calls from your Worker. | |
| Wrangler exposes Artifacts as a first-class binding and returns repo handles for repo-scoped operations such as token management and forking. | |
| Use the Artifacts Workers binding to create, inspect, fork, and delete repos directly from your Worker. The Artifacts binding returns repo handles that allow repo-scoped operations such as token management and forking. |
|
|
||
| Each repository runs its own Git server and keeps persistent internal state on top of SQLite-backed Durable Object storage. A front-end Worker handles authentication and routing, then dispatches requests to the Durable Object for that repository. | ||
|
|
||
|  |
Contributor
There was a problem hiding this comment.
Is it necessary to expose how Artifacts is built here? Will this product be like KV, or more like Agents SDK/Sandbox SDK that bill the underlying?
Contributor
There was a problem hiding this comment.
I would keep the details omitted from this doc, as a reader, I'm just trying to understand Artifacts.
The mention that there it is a "Git server" that can be created on the fly is helpful. The concept that it can be forked, replicated could be represented
| - isolate work in separate repos or branches for safer parallel execution | ||
| - fork from a shared baseline and diff or merge the results later | ||
|
|
||
| Artifacts stores versioned file trees behind a Git-compatible interface, so the same repository can be addressed from [Workers](/workers/), the REST API, and Git clients. Agents already know Git, which means you can give an agent a repository URL, let it work independently, and have it commit its output back to Artifacts with the same tools it already uses elsewhere. You can create one repo per agent, per user, per branch, or per task, scale that pattern to millions of repositories, and keep each unit of work separate until you are ready to compare or merge changes. |
Contributor
There was a problem hiding this comment.
Suggested change
| Artifacts stores versioned file trees behind a Git-compatible interface, so the same repository can be addressed from [Workers](/workers/), the REST API, and Git clients. Agents already know Git, which means you can give an agent a repository URL, let it work independently, and have it commit its output back to Artifacts with the same tools it already uses elsewhere. You can create one repo per agent, per user, per branch, or per task, scale that pattern to millions of repositories, and keep each unit of work separate until you are ready to compare or merge changes. | |
| Artifacts provide a Git-compatible interface to versioned file trees. You can create new repos from [Workers](/workers/), and the REST API. Then, you can use the repo with any Git client, like the [Git CLI](https://git-scm.com/install/) or [Git GUI Clients](https://git-scm.com/tools/guis). | |
| Agents already know Git, which means you can give an agent a repository URL, let it work independently, and have it commit its output back to Artifacts, using the same Git client tools it is already using. | |
| You can create one repo per agent, per user, per branch, or per task, scale that pattern to millions of repositories, and keep each unit of work separate until you are ready to compare or merge changes. |
Comment on lines
+13
to
+40
| ## Fetch the remote and clone the repo | ||
|
|
||
| First, fetch the repo metadata from the REST API. Then mint a read token for that repo and use the returned HTTPS remote with `git clone`. | ||
|
|
||
| The example below uses `jq` to extract fields from the JSON responses. | ||
|
|
||
| ```bash | ||
| export ARTIFACTS_NAMESPACE="default" | ||
| export ARTIFACTS_REPO="starter-repo" | ||
| export ARTIFACTS_JWT="<YOUR_GATEWAY_JWT>" | ||
| export ARTIFACTS_BASE_URL="https://artifacts.cloudflare.dev/v1/api/namespaces/$ARTIFACTS_NAMESPACE" | ||
|
|
||
| REPO_JSON=$(curl --silent "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO" \ | ||
| --header "Authorization: Bearer $ARTIFACTS_JWT") | ||
|
|
||
| ARTIFACTS_REMOTE=$(printf '%s' "$REPO_JSON" | jq -r '.result.remote') | ||
|
|
||
| TOKEN_JSON=$(curl --silent "$ARTIFACTS_BASE_URL/tokens" \ | ||
| --header "Authorization: Bearer $ARTIFACTS_JWT" \ | ||
| --header "Content-Type: application/json" \ | ||
| --data "{\"repo\":\"$ARTIFACTS_REPO\",\"scope\":\"read\",\"ttl\":3600}") | ||
|
|
||
| ARTIFACTS_TOKEN=$(printf '%s' "$TOKEN_JSON" | jq -r '.result.plaintext') | ||
| ARTIFACTS_TOKEN_SECRET="${ARTIFACTS_TOKEN%%\?expires=*}" | ||
| ARTIFACTS_AUTH_REMOTE="https://x:${ARTIFACTS_TOKEN_SECRET}@${ARTIFACTS_REMOTE#https://}" | ||
|
|
||
| git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone | ||
| ``` |
Contributor
There was a problem hiding this comment.
Suggested change
| ## Fetch the remote and clone the repo | |
| First, fetch the repo metadata from the REST API. Then mint a read token for that repo and use the returned HTTPS remote with `git clone`. | |
| The example below uses `jq` to extract fields from the JSON responses. | |
| ```bash | |
| export ARTIFACTS_NAMESPACE="default" | |
| export ARTIFACTS_REPO="starter-repo" | |
| export ARTIFACTS_JWT="<YOUR_GATEWAY_JWT>" | |
| export ARTIFACTS_BASE_URL="https://artifacts.cloudflare.dev/v1/api/namespaces/$ARTIFACTS_NAMESPACE" | |
| REPO_JSON=$(curl --silent "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO" \ | |
| --header "Authorization: Bearer $ARTIFACTS_JWT") | |
| ARTIFACTS_REMOTE=$(printf '%s' "$REPO_JSON" | jq -r '.result.remote') | |
| TOKEN_JSON=$(curl --silent "$ARTIFACTS_BASE_URL/tokens" \ | |
| --header "Authorization: Bearer $ARTIFACTS_JWT" \ | |
| --header "Content-Type: application/json" \ | |
| --data "{\"repo\":\"$ARTIFACTS_REPO\",\"scope\":\"read\",\"ttl\":3600}") | |
| ARTIFACTS_TOKEN=$(printf '%s' "$TOKEN_JSON" | jq -r '.result.plaintext') | |
| ARTIFACTS_TOKEN_SECRET="${ARTIFACTS_TOKEN%%\?expires=*}" | |
| ARTIFACTS_AUTH_REMOTE="https://x:${ARTIFACTS_TOKEN_SECRET}@${ARTIFACTS_REMOTE#https://}" | |
| git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone | |
| ``` | |
| ## Fetch the remote | |
| First, fetch the repo metadata from the REST API. Then mint a read token for that repo and use the returned HTTPS remote with `git clone`. | |
| The example below uses `jq` to extract fields from the JSON responses. | |
| ```bash | |
| export ARTIFACTS_NAMESPACE="default" | |
| export ARTIFACTS_REPO="starter-repo" | |
| export ARTIFACTS_JWT="<YOUR_GATEWAY_JWT>" | |
| export ARTIFACTS_BASE_URL="https://artifacts.cloudflare.dev/v1/api/namespaces/$ARTIFACTS_NAMESPACE" | |
| REPO_JSON=$(curl --silent "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO" \ | |
| --header "Authorization: Bearer $ARTIFACTS_JWT") | |
| ARTIFACTS_REMOTE=$(printf '%s' "$REPO_JSON" | jq -r '.result.remote') | |
| TOKEN_JSON=$(curl --silent "$ARTIFACTS_BASE_URL/tokens" \ | |
| --header "Authorization: Bearer $ARTIFACTS_JWT" \ | |
| --header "Content-Type: application/json" \ | |
| --data "{\"repo\":\"$ARTIFACTS_REPO\",\"scope\":\"read\",\"ttl\":3600}") | |
| ARTIFACTS_TOKEN=$(printf '%s' "$TOKEN_JSON" | jq -r '.result.plaintext') | |
| ARTIFACTS_TOKEN_SECRET="${ARTIFACTS_TOKEN%%\?expires=*}" | |
| ARTIFACTS_AUTH_REMOTE="https://x:${ARTIFACTS_TOKEN_SECRET}@${ARTIFACTS_REMOTE#https://}" | |
| ``` | |
| ## Use the Git client with the remote | |
| Now that you have the authenticated Artifacts remote, you can use it like any other Git repo. Clone the repo and start using it with the [Git CLI](https://git-scm.com/) as such: | |
| ``` | |
| git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone | |
| ``` | |
|
|
||
| | Unit | Workers Free | Workers Paid | | ||
| | ----------------------------- | ------------ | ------------ | | ||
| | Operations (1,000 operations) | coming soon | First 10,000 per month + $0.15 per additional 1,000 operations | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Operations (1,000 operations) | coming soon | First 10,000 per month + $0.15 per additional 1,000 operations | | |
| | Operations (1,000 operations) | Coming soon | First 10,000 per month + $0.15 per additional 1,000 operations | |
| | Unit | Workers Free | Workers Paid | | ||
| | ----------------------------- | ------------ | ------------ | | ||
| | Operations (1,000 operations) | coming soon | First 10,000 per month + $0.15 per additional 1,000 operations | | ||
| | Storage (GB-mo) | coming soon | First 1 GB per month + $0.50 per additional GB-mo | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Storage (GB-mo) | coming soon | First 1 GB per month + $0.50 per additional GB-mo | | |
| | Storage (GB-mo) | Coming soon | First 1 GB per month + $0.50 per additional GB-mo | |
Contributor
|
CI run failed: build logs |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fix code examples to conform.
Documentation checklist