Cloudflare'da Git ve Ajan Mimarisi

Git işlemleri Artifacts üzerinde, sorgulanabilir kayıtlar D1’de, büyük çıktılar ise R2’de tutulabilir. Aktif görevlerin ve eşzamanlı bağlantıların yönetimi içinse Durable Objects kullanılır.

Bir commit kaydının sorgulanabilir alanları D1’de, commit’in ürettiği büyük dosya ise R2’de tutulabilir.

Git katmanı

Cloudflare’ın Artifacts bileşeni, Git ile çalışan sürümlü dosya sistemi olarak kullanılabilir. Artifacts açık beta durumunda ve GitHub gibi upstream depolardan fork oluşturabiliyor. Cloudflare’ın Artifacts açıklamasına göre repo oluşturma, branch üretme, commit oluşturma, diff alma ve arama yapma işlemleri programlanabiliyor.

Worker’lar Artifacts binding üzerinden repo oluşturabilir, fork alabilir, dosyaları ve commit’leri inceleyebilir. Repo kapsamlı Git token’ları da bu binding üzerinden üretilebiliyor. Token’ları yalnızca ihtiyacı olan işlem için kullanmalısınız. Çünkü token’lar belirli repoya ve süreye bağlı olabiliyor.

create() ve import() işlemleri doğrudan uzak repo URL’si döndürüyor. Dönen URL’yi standart Git komutuyla kullanabilirsiniz:

git clone <uzak-repo-url>
git clone --depth 1 <uzak-repo-url>

Bir ajanın workspace’i olarak da Artifacts kullanılabilir. Ortak baseline depodan fork oluşturulur ve çalışma alanına AGENTS.md talimatları verilir.

Ajanın yaptığı değişiklikler workspace içinde commit edilir. Daha sonra bu değişiklikler orijinal repo ile karşılaştırılabilir. Burada benim önerim, ajanın çalıştığı repo ile hedef repo arasındaki sınırı baştan açık tutmak. Aynı repoya doğrudan yazmak yerine, ajanın değişiklikleri ayrı bir çalışma alanında tutulursa hedef branch’e neyin girdiği daha görünür oluyor.

Repo push olaylarına abone olabilirsiniz:

// Worker içinde push olayını dinleyen akış
if (event.type === "cf.artifacts.repo.pushed") {
  await runCI(event.repo);
  await startCodeReviewAgent(event.repo);
}

cf.artifacts.repo.pushed olayına abone olduğunuzda Worker, push olayını CI veya kod inceleme gibi bir iş akışına bağlayabilir. Cloudflare’ın Git platformu yazısında bu olay tabanlı dağıtım senaryosu özellikle vurgulanıyor.

Workers Builds, Artifacts reposunu Worker’a bağlayabilir. Production branch’e yapılan push güncel Worker’ı dağıtabilir. Diğer branch’lere yapılan push ise otomatik paylaşılabilir ve izole Workers Previews oluşturabilir. Böylece her branch’i doğrudan production gibi degerlendirmeye gerek kalmaz; test için ayrı bir dağıtım yolu kullanılır.

Veri katmanı

D1, Worker veya API üzerinden veri alınabilen tablolar ve SQL sorgularıyla çalışır. Repo metadata’sı, kullanıcı bilgileri, ajan görevleri ve commit özetleri için uygun olabilir.

Örneğin bir commit kaydı için şu tableleri düşünebilirsiniz:

CREATE TABLE commits (
  id TEXT PRIMARY KEY,
  repo_id TEXT NOT NULL,
  message TEXT NOT NULL,
  author TEXT NOT NULL,
  created_at TEXT NOT NULL
);

D1, sorgulanabilir kayıtlar için SQL üzerinden çalışır. Yazma sıklığı yüksek işlemlerde D1’in uygunluğunu ayrıca doğrulamak gerekiyor.

R2 ise büyük miktarda yapılandırılmamış veri saklamak için daha uygundur. Build artifact’ları, log dosyaları, büyük çıktılar veya ajan üretimi dosyalar burada tutulabilir. R2’nin geleneksel bulut depolamalarda görülen pahalı çıkış bant genşiliği ücreti olmamasıyla ayrıldığı belirtiliyor. Durum ve depolama seçeneklerine göre R2, büyük ve yapılandırılmamış veri için daha uygun görünüyor.

Seçimde veri şekli kadar erişim biçimi de belirleyici. SQL ile sorgulanması gereken kayıtlar için D1, dosya veya çıktı saklamak için R2, aktif görevleri ve istemciler arasındaki eşzamanlı bağlantıları yönetmek için Durable Objects daha uygun bir başlangıç noktası sunuyor. Tek bir servis yerine bu ayrımı baştan kurmak, ileride büyük ölçekli bir yeniden yazım ihtiyacını azaltabilir; ancak her işlem için aynı sınırların geçerli olmadığını unutmayın.

Ajan çalışma alanları

Ajan çalışma alanı, ortak bir baseline depodan fork oluşturularak izole hâle getirilebilir. Bu workspace’e AGENTS.md dosyasını ekleyebilirsiniz. Dosyaya repo kurallarını, test komutunu ve çalışma alanı sınırlarını yazabilirsiniz.

AgentSandbox yaklaşımında her sandbox kendi container’ına sahip bir AgentSandbox Durable Object olarak çalışıyor. Bir Durable Object başına aynı anda yalnızca bir Claude Code görevi yürütülüyor. Sandbox kurulum dokümantasyonunda bu sınır özellikle belirtiliyor. Aynı object içinde birden fazla görevi üst üste çalıştırmak yerine, her workspace’in sınırlarını ayrı tutmak daha açık bir model oluşturuyor.

Agent’ın oluşturduğu değişiklikleri şu komutla inceleyebilirsiniz:

git add --intent-to-add . && git diff

Çıktıyı ve workspace’in commit geçmişini inceleyerek ajanın hangi dosyalara dokunduğunu görebilirsiniz. Diff ve commit geçmişini inceledikten sonra yalnızca hedef branch’e alınacak değişiklikleri workspace’ten aktarın.

Cloudflare OS’ta her çalışma alanı kendi Durable Object’i üzerinde çalışıyor. Her Gadget ise ayrı bir Dynamic Worker Facet içinde yürütülüyor. Bu ayrım, uygulama parçalarını birbirinden ayırmak için kullanışlı.

Gadget sunucusunda internet erişimi açıkça izin verilmedikçe kapalı. Harici kaynaklarla iletişim yalnızca belirtilmiş Workers Bindings üzerinden gerçekleşebiliyor. Bu nedenle ajanın yalnızca tanımlı kaynaklara bağlanmasını ve rastgele URL’lere erişmesini beklemiyorsanız, model güvenlik açısından kabul edilebilir bir sınır oluşturuyor.

Durum ve güvenlik

Durable Objects hesaplama ile kalıcı depolamayı tek yapı taşında birleştiriyor. Birden fazla istemcinin birlikte çalışması gerektiğinde koordinasyon sağlayabiliyor. Oturum ve WebSocket bağlantıları için seçenek oluşturuyor. Durable Objects dokümantasyonu alarm mekanizması ve kalıcı depolama özelliklerini de anlatıyor.

Bir object yalnızca görev durumunu, bağlantı yönetimi için kullandığınız başka bir object ise istemci bağlantılarını yönetsin. Gatekeepers ise Gadget veya ajan eylemlerini kaydediyor. Harici servislere erişimi kaynak bazında daraltıyor ve OAuth gibi yetkilendirme yöntemlerini kullanabiliyor. Yan etkili işlemler için toplu veya tek tek onay sunulabiliyor.

Onay bekleyen eylemin sonucu yerel olarak simüle edilebilir. Böylece ajan çalışmaya devam eder, gerçek eylemler ise kullanıcı onayından sonra yürütülebilir. Onay bekleyen eylemin sonucunu yerel olarak simüle edip çıktıyı gerçek servise göndermeden önce inceleyin.

Cloudflare OS’u yerel sunucuda denemek için notlarda verilen hızlı başlanıgç komutunu kullanabilirsiniz:

pnpm run-local

Mimariyi kurarken katmanların bağımsız geliştirilebildiği görülüyor. Repo ve branch akışını Artifacts ile kurup metadata sorgularını D1’ye eklemek, büyük çıktıları R2’den ayırmak daha yönetilebilir bir ilerleme sağlıyor. Görev koordinasyonu ve dış kaynaklara erişim ise Durable Objects ile Gatekeepers tarafında ele alınabilir; bu katmanların hepsini tek bir servis içinde birleştirmek yerine sorumlulukları ayrı tutmak daha sağlıklı.

Kaynaklar

• We want you to build the next Git platform on Cloudflare (Cloudflare Blog)

• cloudflare/cloudflare-os: Agent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems. (GitHub)

• Git integration (Cloudflare Docs)

• Cloudflare Artifacts (cloudflare.com)

• GitHub - cloudflare/workers-for-platforms-example: A great place for ... (GitHub)

• Cloudflare OS: your company’s agent workspace, managed for you (cloudflare.com)

• Build a coding agent runner (Cloudflare Docs)

• Cloudflare KV vs D1 vs R2 vs Durable Objects (flaviocopes.com)

• Overview · Cloudflare Durable Objects docs (Cloudflare Docs)