Artifacts

Artifacts nedir?

Çözdüğü problem, duyurudan birebir:

“Source control platforms are especially struggling here: they were built to meet the needs of humans, not a 10x change in volume driven by agents who never sleep.”

Neden Git? “Agents know Git. It’s deep in the training data of most models.”

Nasıl çalışır?

Mimari

Her depo bir Durable Object’tir. Git sunucusu saf Zig ile yazılmış, WASM’a derlenmiş ~100 KB’lık bir ikili: SHA-1, zlib, delta kodlama, pack ayrıştırma ve tam Git smart HTTP protokolü.

Dosyalar Durable Object’in SQLite veritabanında durur; 2 MB satır sınırı yüzünden büyük Git nesneleri parçalara bölünür. R2 yalnızca snapshot’lar için, KV token takibi için kullanılır.

Nesne modeli: Namespace → Depo. Namespace örtük olarak oluşturulur — yeni bir namespace adıyla ilk depoyu yarattığında Artifacts onu da yaratır.

Protokol desteği

v1’de bazı yetenekler de eksik: filter ve include-tag.

Git remote biçimi:

https://<HESAP_ID>.artifacts.cloudflare.net/git/<namespace>/<depo>.git

Token modeli

Biçim: art_v1_<40 hex>?expires=<unix saniye>. İki kapsam: read (clone/fetch/pull) ve write (push dahil). TTL 60 saniye ile 1 yıl arası.

İki farklı token tipini karıştırma:

Bunlar birbirinin yerine kullanılamaz.

git notes desteği

Agent metadata’sını commit’lere iliştirmenin belgelenmiş yolu — “without mutating the objects themselves.” Uyarı: notes ayrı ref’lerde durur, refs/notes/* de push ve fetch edilmeli, yoksa metadata sessizce kaybolur.

ArtifactFS

Cloudflare, github.com/cloudflare/artifact-fs adresinde açık kaynak bir FUSE sürücüsü yayımlıyor. Önce blobsuz clone yapıp arka planda paket manifestlerini ve config dosyalarını önceliklendirerek dolduruyor. Blog iddiası: 2,4 GB’lık bir deponun clone süresi *“close to 2 minutes”*ten *“~10-15 seconds”*e iniyor. Herhangi bir Git remote’uyla çalışıyor, yalnızca Artifacts ile değil.

Ne zaman kullanılır, ne zaman kullanılmaz

Uygun olduğu işler

• Oturum başına izole çalışma alanı gereken AI agent’ları
• Ortak bir temelden fork’layıp paralel çalışan agent’lar
• Programatik olarak oluşturulup silinen kısa ömürlü depolar
• Versiyonlanabilir müşteri yapılandırması saklama (geri alma yeteneğiyle)

Uygun olmadığı işler

• Beta erişimin yoksa hiçbir şey. Beş aydır kapalı.
• Ücretsiz plan. Kullanılamaz.
• 10 GB’ı aşan depolar. Sert tavan.
• İnsan işbirliği. PR yok, code review yok, issue yok, branch protection yok.
• Paket veya container registry ihtiyacı. Bu ürün onu yapmıyor.
• Düz blob depolama. R2 hem sınırsız hem 33 kat ucuz.
• Protokol v2 ile push. Desteklenmiyor.

Yerleşik alternatiflere karşı dürüst konum

Olgunluk değerlendirmesi: bu portalda incelenen en olgunlaşmamış ürün. Kapalı beta, ücretsiz katman yok, kaçırılmış public beta tarihi, duyurulandan farklı şipilen bir özellik, ve kendi dokümantasyonu içinde tutarsız URL’ler.

Somut örnekler

1. Oturum başına depo — kanonik desen

{
  "name": "artifacts-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-01",
  "artifacts": [{ "binding": "ARTIFACTS", "namespace": "varsayilan" }]
}

// Docs önerisi: çakışmayı önlemek için benzersiz adlandırma
async function oturumDeposuAc(env, agentAdi, oturumId, depoAdi) {
  const benzersizAd = `${agentAdi}-${oturumId}-${depoAdi}`;
  return env.ARTIFACTS.create(benzersizAd);
}

2. Temel depoyu içe aktar, oturum başına fork’la

// Bir kez: dış depoyu içe aktar
const iceAktarilan = await env.ARTIFACTS.import({
  source: { url: "https://github.com/sirket/temel-sablon", branch: "main" },
  target: { name: "temel-sablon" },
});

// Her oturum: fork'la
const temel = await env.ARTIFACTS.get("temel-sablon");
const fork = await temel.fork(`temel-${oturumId}`, {
  description: `${oturumId} oturumu için fork`,
  defaultBranchOnly: true,
  readOnly: false,
});

return { remote: fork.remote, token: fork.token };

3. Kısa ömürlü, dar kapsamlı token

const depo = await env.ARTIFACTS.get(depoAdi);
const token = await depo.createToken("read", 900);   // 15 dakika, yalnızca okuma

return Response.json({
  kapsam: token.scope,
  bitis: token.expiresAt,
  token: token.plaintext,
});

4. Agent metadata’sını git notes ile taşıma

git notes add -m 'kullanıcı: Benzersiz depo adları için en iyi uygulama bölümü ekle.' HEAD
git notes append -m 'asistan: Adlandırma rehberi ve kod örneği eklendi.' HEAD
git notes show HEAD

# Metadata'nın taşınması için notes ref'ini de push et
git push origin 'refs/notes/*'

5. Git istemcisi olmadan dosya okuma

curl "$ARTIFACTS_BASE_URL/repos/$DEPO/file?ref=main&path=yapilandirma.json" \
  --header "Authorization: Bearer $CF_API_TOKEN"

Bu, “versiyonlanabilir müşteri yapılandırması” kullanımını mümkün kılar — Git semantiğinden yararlanırsın ama okuma tarafında Git istemcisine ihtiyacın olmaz.

Demo 1: Programatik depo oluşturma ve klonlama

Adım 1 — Namespace ve depo oluştur

npx wrangler artifacts namespaces list
npx wrangler artifacts repos create demo-depo --namespace varsayilan

Terminal — oluşturulan deponun adı, remote URL'i ve durumu

Adım 2 — Token üret

npx wrangler artifacts repos issue-token demo-depo \
  --namespace varsayilan --scope write --ttl 3600

Terminal — art_v1_ ile başlayan token ve expires parametresi

Adım 3 — Klonla

git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" \
  clone "$ARTIFACTS_REMOTE" demo-klon

Terminal — başarılı clone çıktısı ve klasör içeriği

Adım 4 — Push et

Terminal — commit ve push çıktısı; protokol v1 kullanıldığı görünsün

Adım 5 — Protokol v2 ile push’un başarısız olduğunu göster

git -c protocol.version=2 push origin main

Terminal — v2 receive-pack desteklenmediğini gösteren hata

Demo 2: Agent deseni — fork ve izolasyon

Adım 1 — Temel depoyu içe aktar

Terminal veya API çıktısı — import işleminin başlaması ve durum alanının 'importing' olması

Adım 2 — Üç oturum için fork oluştur

Üç fork işleminin çıktısı ve her birinin farklı remote URL'i

Adım 3 — İzolasyonu doğrula

Bir fork’a commit at, diğerlerinde görünmediğini göster.

İki fork'ta git log çıktısı — birinde yeni commit var, diğerinde yok

Adım 4 — git notes ile metadata ekle

git notes show çıktısı — commit'e iliştirilmiş prompt ve agent bilgisi

Adım 5 — Kullanımı gözle

Panel veya GraphQL sorgusu — repo başına işlem sayısı ve depolama kullanımı

Ölçüm

Fiyatlandırma

İşlem tanımı: “the number of repo operations, such as create, push, pull, and clone.”

Depolama notları:

• GB-ay, 30 günlük dönemde günlük tepe kullanımın ortalamasıdır
• Tüm depolar üzerinden hesaplanır
• Replikalar ek depolama ücreti doğurmaz — replikasyon varsayılan olarak açıktır
• Depolar açıkça silinene kadar saklanır

Limitler

Ad kuralı: harf veya rakamla başlamalı; kalan karakterler harf, rakam, ., _ ve - olabilir.

Lisanslama ve hukuki çerçeve

Artifacts tescilli bir hizmettir; Cloudflare Hizmet Şartları kapsamındadır.

Veri yerleşimi: Namespace oluşturulurken eu veya us yargı bölgesi verilebilir ve bu ayar sonradan değiştirilemez. Türkiye için tanımlı bölge yoktur.

İçe aktarılan depoların lisansı. Dış bir Git deposunu Artifacts’e içe aktarıyorsan o deponun lisans koşulları geçerli olmaya devam eder. Özellikle agent’lara fork ettirdiğin temel şablonlarda buna dikkat et.

Agent’ların ürettiği kod. Depolarda biriken kodun telif durumu, üreten modele ve kullanım şartlarına bağlıdır. git notes ile hangi prompt’un hangi commit’i ürettiğini kaydetmek, bu soruya sonradan cevap verebilmek açısından pratik bir alışkanlıktır.

Sık yapılan hatalar

Paket veya build deposu sanmak. Git deposu saklar; kategori hatası yapma.

Kısa ve paylaşılan depo adı kullanmak. ${agentAdi}-${oturumId}-${depoAdi} biçimini kullan.

Tek paylaşılan depoyu çok agent için kuyruk olarak kullanmak. Açıkça uyarılmış anti-desen.

Uzun ömürlü write token dağıtmak. Varsayılan read olsun, TTL kısa olsun, oturum başına yeniden üret.

İki token tipini karıştırmak. Cloudflare API token’ı kontrol düzlemi, Artifacts token’ı Git içindir.

Token’ın tamamını Basic-auth URL’ine koymak. Önce ?expires= sonekini ayırman gerekir.

import ve fork sonrası 409 Conflict durumunu ele almamak. İkisi de asenkron.

refs/notes/* senkronizasyonunu unutmak. Agent metadata’sı sessizce kaybolur.

Her şeyi tek namespace’e yığmak. Hız sınırları namespace başınadır.

Token üreten uç noktayı kimlik doğrulamasız bırakmak. Docs’un kendi örneğinde bile uyarı var: “In production, authorize the caller before creating repos or returning tokens.”