Ortamları kurma
Ortam, bir alanın çalışan yığınıdır: bir dalın ihtiyaç duyduğu servisler, diğer tüm alanlardan yalıtılmış, kenar çubuğunda görünür ve ajanların erişebileceği biçimde. Pull request’ler de bir tane alır, çünkü bir PR’ın zaten kendi alanı vardır.
Bir çalışma alanı yöneticisi bir kez tanım yazar. Üyeler ardından bir alanın veya PR’ın kenar çubuğundaki Ortam bölümünde Başlat düğmesine basar. Tanımlar çalışma alanının veritabanında durur, bu yüzden bir özellik dalı Control Center’ın ne çalıştırdığını asla değiştirmez; yine de araçlar o dalın kodunu çalıştırır.
Tanım oluşturma
Bölüm başlığı “Tanım oluşturma”- Ayarlar → Çalışma alanı → Ortamlar yolunu açın. Tanımları yalnızca çalışma alanı yöneticileri değiştirebilir; sunucu ana makinesinde çalışan birini yalnızca sunucu sahibi kaydedebilir (bkz. Kimin neyi kaydedebileceği).
- Yeni tanım düğmesine, ardından Boş tanım veya Depodan taslak oluştur seçeneğine tıklayın. Taslak, depoda compose dosyaları, bir
Procfilevepackage.jsonbetikleri arar; sonucu siz gözden geçirirsiniz. - Formu doldurun veya JSON sekmesini kullanın. Bu sayfadaki örnekler o JSON’dur.
- Testi çalıştır düğmesine tıklayın. Tek kullanımlık bir ortam başlatır, hazır olmasını bekler ve onu yok eder.
Kaydetme, bir tanımı sıkı biçimde denetler. Bilinmeyen bir alan, yanlış türde bir değer veya yanlış yazılmış bir seçenek, yolu ve en yakın geçerli adıyla birlikte reddedilir, örneğin repos.app.requird: Unknown field. Did you mean "required"?. En üst düzeyde bir $schema kabul edilir.
Bir tanımı depoda tutmak için Depo dosyası bağla seçeneğini kullanın. Control Center dosyayı yalnızca varsayılan daldan okur ve yalnızca onaylanan sürümü çalıştırır: bir çalışma alanı yöneticisi tarafından ya da tanım ana makinede çalıştığında sunucu sahibi tarafından. Daha yeni bir sürüm Güncelleme var gösterir ve onaylanana kadar hiçbir şeyi değiştirmez.
Kimin neyi kaydedebileceği
Bölüm başlığı “Kimin neyi kaydedebileceği”Bir ortam tanımı, sunucunun kendi kullanıcısı olarak sunucu ana makinesinde komut çalıştırabilir. Bu, bir çalışma alanı rolünün değil, sunucu sahibinin kararıdır:
- Bir tanım ana makinede çalışır; ana makine yerleşimine, bir komut çalıştıran bir denetime ya da bir
provisionveyaarchivegörevine sahip olduğunda. Bu görevler, yerleşim ne olursa olsun alanın worktree’sinde ana makinede çalışır. - Yalnızca sunucu sahibi ana makinede çalışan bir tanımı kaydedebilir ya da onaylayabilir. Bu, bağlı bir depo dosyasının yeni bir sürümünü onaylamayı da kapsar. Bunu deneyen bir çalışma alanı yöneticisi şu mesajı görür: “Sunucu host’unda çalışan bir ortamı yalnızca sunucu sahibi kaydedebilir veya onaylayabilir. Bir çalışma alanı yöneticisi rig’de çalışan bir ortamı kullanabilir.”
- Bir çalışma alanı yöneticisi, tamamen bir rig’de çalışan bir tanımı kaydedebilir ve onaylayabilir:
"placement": "rig", komut denetimi yok veprovisionya daarchivegörevi yok. - Üyeler her iki durumda da ortamları başlatır, durdurur ve kullanır.
- Ana makinede çalışan bir tanım yalnızca geçerli sunucu sahibi onu kaydettikten ya da onayladıktan sonra çalışır. Sunucu bu onayı kendisi kaydeder ve her başlatmadan, denetimden, görevden ve pull request head senkronizasyonundan önce denetler. Geçerli sahibin onaylamadığı bir tanım, örneğin önceki bir sahibin kaydettiği bir tanım, ortam listesinde kendi satırının altında ve düzenleyicide bekler. Sunucu sahibi Onayla ile “Bu sunucuda çalışır. Başlayabilmesi için onaylayın.” mesajını görür; bu, tanımı değiştirmeden kaydeder. Diğer herkes “Bu sunucuda çalışır. Başlayabilmesi için sunucu sahibinin onaylaması gerekir.” mesajını görür.
- Bu onay için bekletilen bir ortam “Sunucu sahibi bu ortamı henüz onaylamadı, bu yüzden bu sunucuda çalışamaz.” der. Sunucu sahibi ise bunun yerine “Bu ortamı henüz onaylamadınız. Bu sunucuda çalışır, bu yüzden tanımını onayladığınızda başlar.” mesajını görür ve İncele ve onayla ile tanımı açar.
- Bir ortamın süreç terminalleri ve bir başlatmanın size ihtiyaç duyduğunda açtığı terminal, sunucu ana makinesinde çalışır. Bu terminallere yazmak, boyutlarını değiştirmek ya da kapatmak için alanın açığa çıkardığı her depoya yazma erişimi gerekir; bu erişim kendi forge oturum açmanızla okunabilir: ortamı başlatmakla aynı. Başkaları bu terminallere hiç erişemez.
En küçük tanım
Bölüm başlığı “En küçük tanım”Basit bir compose deposu için bu kadarı yeterlidir:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Geri kalan her şeyin varsayılanı vardır: compose dosyası bulunur, tüm servisler çalışır, bağlantı noktaları atanır, HTTP uç noktaları algılanır ve ortam adını daldan alır.
Bileşen türleri
Bölüm başlığı “Bileşen türleri”Ortam, sıralı bir bileşen listesidir. after başkalarını belirtmedikçe her biri bir öncekinin hazır olmasını bekler ve durdurma ters sırada gerçekleşir. enabledWhen bir bileşeni bir seçeneğe veya role bağlar; örneğin opt.seed, !opt.seed veya repo.web. İsteğe bağlı bir rolü olup alanda bulunmayan bileşen de aynı biçimde dışarıda bırakılır, enabledWhen gerekmeden: başlamaz ve {port.*} ya da {url.*} değerlerine sahip olmaz; bu nedenle bunları okuyan başka bir bileşen başlatmada başarısız olur.
| Tür | Kim çalıştırır | Ne için |
|---|---|---|
compose |
Control Center’ın compose sürücüsü | Her compose dosyası, ortam başına bir tane |
cli |
Aracınız. Control Center eşlenen fiilleri çağırır ve JSON okur | Yaşam döngüsünü, alan adlarını ve verisini kendi yöneten bir araç |
process |
Control Center, denetlenen bir terminal oturumunda | Geliştirme sunucuları ve worker’lar |
task |
Control Center, tetikleyici başına bir kez | Kurulumlar, geçişler, testler |
app |
Control Center, biri Aç düğmesine bastığında | Bir masaüstü uygulaması |
task bileşenleri bir when listesi alır:
| Tetikleyici | Ne zaman çalışır |
|---|---|
provision |
Worktree oluşturulduğunda (aşağıdaki worktree görevlerine bakın) |
create |
Ortam başına bir kez ve sıfırlamadan sonra yeniden |
start |
Her başlatmada |
change |
Eşitlemeden sonra, değişen bir yol onChange ile eşleştiğinde |
manual |
İstek üzerine: Çalıştır, cc-env run <id> veya environment_run_task |
archive |
Worktree yok edilmeden hemen önce |
Başlatmada yapacak işi olmayan bir görev Boşta durumunu gösterir ve ortam başlarken gösterilen adım listesinde yer almaz: manual ya da change görevi ya da daha önce çalışmış bir create görevi.
Dizi olarak verilen bir komut argv’dir, bu nedenle seçenek değerleri asla bir kabuktan geçmez. Bir dize veya satır dizisi içeren script, bash -lc altında çalışır. {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} ve {url.<role>} gibi yer tutucular yalnızca argv içinde genişletilir. Kabuk komutları aynı değerleri $CC_ENV_PORT_WEB gibi CC_ENV_* değişkenlerinden okur. Katılan bir bileşende bilinmeyen bir yer tutucu, hiçbir şey çalışmadan önce başlatmayı durdurur.
Her komut ve alan terminali ayrıca CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> ve PR alanlarında CC_PR_NUMBER ile CC_PR_IS_FORK alır. Bir compose bileşeniyle COMPOSE_PROJECT_NAME ve COMPOSE_FILE de gelir; böylece bir görevdeki docker compose exec doğru projeye ulaşır.
Roller ve çalışma dizini
Bölüm başlığı “Roller ve çalışma dizini”Tanım, rolleri çalışma alanı depolarına bağlar; böylece bir yığın birden çok depoyu kapsayabilir:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: bir alan en az bir çapa rolü içeriyorsa ortamı başlatabilir. İki tanım eşleşirse başlatan kişi seçer.required: yığın bu depo olmadan çalışamaz.whenMissing: alanda rol eksik olduğunda ne olacağı.addToSpacedepoyu varsayılan dalında ekler verequiredrollerin varsayılanıdır.useSourcekayıtlı kopyanızı aktarır; bunu salt okunur kabul etmelisiniz.skipdeğişkeni boş bırakır ve diğer durumlarda varsayılandır.- Başlatmak için alandaki bir çapa deposunda
writeizni ve bağlı diğer tüm depolarda okuma erişimi gerekir.
Bir komut, repos içinde bildirilen ilk rolde çalışır, alanın tesadüfen sahip olduğu başka bir rolde hiçbir zaman; bu yüzden tek depolu bir tanım bundan hiç söz etmez. Her bileşen bunu "cwd": { "role": "e2e", "path": "packages/ui" } ile değiştirebilir. Her iki alan da isteğe bağlıdır. İlk rolün bir alanda bulunmayabileceği durumlarda, çünkü ne required ne de tek bağlantı noktasıdır, her bileşen rolünü adıyla belirtmek zorundadır.
Bağlantı noktaları ve URL’ler
Bölüm başlığı “Bağlantı noktaları ve URL’ler”Control Center, bir şey başlamadan önce ana makine bağlantı noktalarını tüm ana makine için ortak bir aralıktan atar (varsayılan olarak 42000-49999, 32’lik bloklar halinde). Bir bağlantı noktası ortamın ömrü boyunca aynı kalır ve compose bağlantı noktaları yalnızca 127.0.0.1 adresine bağlanır.
- Compose bağlantı noktalarının bildirilmesi gerekmez. Bunları
{port.postgres.5432}veyaCC_ENV_PORT_POSTGRES_5432olarak okuyun. - Diğer bağlantı noktaları kullanıldıkları yerde
"port": "web"veya"ports": ["web", "hmr"]ile bildirilir ve{port.web}olarak okunur. Bağlantı noktası olan bir süreç ayrıcaPORTveHOST=127.0.0.1alır.
HTTP uç noktaları, tek bir loopback bağlantı noktasını dinleyen sunucu yönlendiricisinde bir URL alır:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>, dalın slug halidir veya bir PR alanındapr-<n>olur.<project>,naming.projectdeğeridir; yoksa tanımın adıdır.*.localhostadları loopback’e çözümlenir, bu yüzden hosts girdisi veya DNS gerekmez ve ana makine adı ortamlar arasında çerezleri ayrı tutar.- HTTP yanıtı veren compose bağlantı noktaları algılanır ve bileşendeki
httpbu tahminin yerini alır. Bir süreç"endpoint": { "role": "web", "primary": true }gerektirir; bu aynı zamanda{url.web}değerini kullanılabilir yapar. - Tarayıcıda (VM) Browser (VM) içinde aç seçeneğini kullanın.
https://web--fix-login--shop.localhost/orada aynı rotaya ulaşır. - Etiketin tamamı 63 karakteri aşmaz, bu yüzden uzun adlar bir karma ile kısaltılır.
- İki uç noktanın ortak üst alan adı yoktur. İkisinde tek çerez isteyen bir uygulama onları tek uç noktadan sunmalıdır.
OAuth yönlendirmeleri gibi önceden kaydedilmesi gereken URL’ler için "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } sabit bir ad kümesi sağlar.
policy, ortamların ne zaman çalışacağına karar verir. autoCreate değeri off, prSpaces veya allSpaces olur, idleStopMinutes varsayılan olarak 240’tır, followPrHead head’i hareket ettiğinde PR ortamını eşitler ve maxRunning (varsayılan 6) sayesinde Başlat en uzun süredir kullanılmayan ortamı durdurmayı önerir.
Örnek: compose uygulaması
Bölüm başlığı “Örnek: compose uygulaması”Tek bir compose dosyasından bir web uygulaması ve Postgres; git tarafından yok sayılan bir .env, geçişler ve bir test görevi ile. seedFiles, adı verilen dosyaları kayıtlı kopyanızdan her yeni worktree’ye kopyalar.
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}healthchecks, kendi sağlık denetimi olmayan bir servisin sonraki bileşeni bekletmesini sağlar. Bu olmadan çalışan bir kapsayıcı hazır sayılır ve geçişler hâlâ başlamakta olan bir veritabanının önüne geçebilir.
Her başlatma ve yenileme, up komutunu --remove-orphans ile çalıştırır; böylece compose dosyasından kaldırılan bir servis durur ve bağlantı noktasını serbest bırakır. Görüntüler başlatmada ve yenilemede, bileşen "build": false ayarlamadığı sürece oluşturulur.
Örnek: özel CLI
Bölüm başlığı “Örnek: özel CLI”Kapsayıcılarını, alan adlarını ve TLS’ini kendi yöneten uydurma bir acme aracı. Control Center {name} değerini sağlar ve geri kalan her şeyi status çıktısından öğrenir. Bir aracın ana makine adlarını asla türetmez ve /etc/hosts dosyasını asla düzenlemez.
{ "contract": 1, "name": "Acme", "repos": { "server": { "repoId": "<server>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true } }, "routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443", "tls": true, "caFile": "~/.acme/tls/ca.crt" }, "components": [ { "kind": "cli", "id": "acme", "verbs": { "create": ["acme", "env", "create", "{name}", { "if": "!interactive", "args": ["--json"] }, { "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }], "start": ["acme", "env", "start", "{name}"], "stop": ["acme", "env", "stop", "{name}"], "destroy": ["acme", "env", "destroy", "{name}", "--yes"], "reset": ["acme", "env", "reset-db", "{name}"], "status": ["acme", "env", "status", "{name}", "--json"], "list": ["acme", "env", "ls", "--json"], "logs": ["acme", "env", "logs", "{name}", { "if": "service", "args": ["{service}"] }, "--tail", "{tail}", { "if": "follow", "args": ["--follow"] }], "exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"] }, "interactive": ["create"], "keepsDataOnStop": false, "statusMap": { "state": [ { "when": { "path": "/status/ready", "equals": true }, "state": "ready" }, { "when": { "none": "/status/containers", "where": { "state": "running" } }, "state": "stopped" }, { "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" }, { "state": "starting" } ], "detail": "phase: {/status/phase}", "warnings": [ { "when": { "path": "/status/dnsWorking", "equals": false }, "message": "Not resolvable on this host" } ], "endpoints": [ { "role": "app", "label": "App", "url": "/urls/app", "primary": true }, { "role": "db", "hostPort": "/ports/db" } ], "services": "/status/containers/*/service", "list": "/*/slug", "missingErrorCodes": ["env.not-found"] } } ]}create,statusvedestroyzorunludur. Control Center, okuduğu duruma görecreateveyastartseçer. Her fiil argv yerine{ "shell": "…" }olabilir.interactive,create,startveresetiçinden, ihtiyaç duyduğu şeyi bir terminalde sorabilen fiilleri adlandırır. Başlat düğmesine basan kişi için böyle bir fiil 3 koduyla çıktığında Control Center aynı fiili bir terminal sekmesinde yeniden çalıştırır ve başlatma, fiil 0 koduyla çıktığında devam eder. Oradainteractivekoşulu doğrudur veCC_ENV_INTERACTIVE=1ayarlanır; bu nedenle{ "if": "!interactive", "args": ["--json"] }makine çıktısını boru hattı için korur. Bir ajanın ya da otomatik bir başlatmanın hiçbir zaman terminal açmaz: ortam İşlem gerekli gösterir ve bekler.destroybaşarısız olsa da, ardındanstatusmissingbildirirse ortam yine de kaldırılır; böylece araç artık sahip olmadığı bir ortam her zaman kaldırılabilir.list, Control Center’ın aracın kaybettiği bir ortamı fark etmesini sağlar. Ortam, adılistiçinde yoksa vestatusardındanmissingdiyorsa kayıp olarak işaretlenir. Liste olarak okunamayan çıktı hiçbir şeyi değiştirmez.logsveexeciçindeki{service},-ile başlamayan tek bir kelime olmalı ve araç bir şey bildirdiğinde son bildirdiği servislerden biri olmalıdır.statusMap, aracın kendi JSON’unu JSON işaretçileriyle okur;*her öğeyle eşleşir. Durum kuralları sıralıdır ve ilk eşleşme kazanır. Bir koşulequalsilepathya dawhereileanyveyanoneşeklindedir.keepsDataOnStop: falseboşta durdurmayı kapatır ve Durdur işlemine veri kaybı uyarısı ekler. Durdurma veri kaybettiriyorsa bunu ayarlayın.routing.mode: "tool"aracın ana makine adlarını tarayıcıya (VM) ve ajanlara bağlar. Alan adı.test,.localhostveya.internalile bitmelidir ve bunun dışında bildirilen bir URL atılır.
Size ait bir araç statusMap kullanmadan bu sayfanın sonunda açıklanan durum sözleşmesini yazdırabilir.
Örnek: pnpm monorepo
Bölüm başlığı “Örnek: pnpm monorepo”Yalnızca süreçler ve görevler, kapsayıcı yok. Web uygulaması API’yi {url.api} üzerinden bulur.
{ "contract": 1, "name": "Monorepo", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "mono" }, "options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ], "components": [ { "kind": "task", "id": "install", "when": ["provision", "change"], "onChange": ["pnpm-lock.yaml"], "command": ["pnpm", "install", "--frozen-lockfile"] }, { "kind": "process", "id": "api", "label": "API", "port": "api", "cwd": { "path": "apps/api" }, "command": ["pnpm", "dev"], "endpoint": { "role": "api" }, "ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 }, "restartOn": ["pnpm-lock.yaml"] }, { "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed", "cwd": { "path": "apps/api" }, "command": ["pnpm", "db:seed"] }, { "kind": "process", "id": "web", "label": "Dev server", "port": "web", "cwd": { "path": "apps/web" }, "env": { "API_URL": "{url.api}" }, "command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"], "endpoint": { "role": "web", "primary": true }, "ready": { "http": "http://127.0.0.1:{port.web}/" } }, { "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] } ]}- Her süreç, açıp okuyabileceğiniz ve içine yazabileceğiniz bir terminal sekmesidir; alanın her deposuna yazma erişiminiz varsa (bkz. Kimin neyi kaydedebileceği). Sekmeyi kapatmak süreci durdurmaz.
ready,http(tam bir URL),tcp(host:port) veyalogMatch(düzenli ifade) alır.restart,on-failure(varsayılan),alwaysveyaneverolur.restartOn, değişen bir yol eşleştiğinde süreci yeniden başlatır.options, Başlat üzerinde bir forma dönüşür veagentDefaultbir ajanın başlattığı çalıştırmalar için geçerlidir.
Örnek: masaüstü uygulaması
Bölüm başlığı “Örnek: masaüstü uygulaması”Derleme adımı olan bir masaüstü uygulaması. Bir uygulama neyle yapılmış olursa olsun aynı şekilde çalışır, çünkü Control Center işletim sistemi pencere düzeyinde çalışır ve uygulamada kanca ya da SDK gerektirmez.
{ "contract": 1, "name": "Studio", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] }, { "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build", "command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"], "isolate": "home" } ]}Bir uygulama ortamla birlikte başlamaz. Biri Aç düğmesine basar ve önce prepare çalışır. Yeniden derle ve aç bu ikiliyi yeniden çalıştırır. enabledWhen uygulamaya ve onun prepare görevine uygulanır; ikisinden biri kapalıyken Aç reddedilir. Uygulama, süreç grubundaki herhangi bir süreç çalıştığı sürece çalışıyor sayılır; bu yüzden uygulamayı başlatıp çıkan bir başlatıcı sorun değildir. Aç düğmesine basıldıktan yaklaşık 5 saniye içinde her şey ortadan kalkarsa uygulama son günlük satırlarıyla başarısız görünür. Bundan sonra temiz bir çıkış kapalı olarak, bir çökme ise son günlük satırlarıyla görünür ve hiçbiri uygulamayı yeniden başlatmaz. Sunucunun yeniden başlaması uygulamayı kapatır ve asla yeniden açmaz; boşta durdurma ise çalışan bir uygulamaya dokunmaz.
Masaüstü uygulaması izinleri ve sınırları
Bölüm başlığı “Masaüstü uygulaması izinleri ve sınırları”- macOS’ta Control Center’a Sistem Ayarları’ndan bir kez Ekran Kaydı ve Erişilebilirlik izni verin. Sunucu ana makinesi bir grafik oturumu gerektirir: başsız bir sunucu uygulama başlatmayı reddeder.
- İkili dosyayı doğrudan başlatın.
open -auygulamayı LaunchServices’e verir ve uygulama Control Center’ın izlediği süreç ağacından çıkar, bu yüzden uygulama başlatıldıktan hemen sonra başarısız görünür. - Pencereler bir ekranda kalır. macOS tüm ekranların dışına park edilmiş bir pencereyi yakalamaz, bu yüzden bir ajanın kullandığı uygulama sunucunun ekranında görünür. Odak gerekmez.
"isolate": "home",HOME,XDG_*veCFFIXED_USER_HOMEüzerinden uygulamaya özel bir ana dizin verir; böylece iki alandan kopyalar yan yana çalışabilir.NSUserDefaultsyalıtılmaz, bu yüzden Cocoa tercihleri ve Flutter’ınshared_preferencesdeposu kopyalar arasında paylaşılır.isolateyalnızca başlatılan süreç için geçerlidir.flutter rungibi bir araç zinciri başlatıcısı gerçek ana dizine ihtiyaç duyar, bu yüzdenisolateseçeneğini derlenmiş bir ikili dosyayla kullanın. Uygulamanın--user-data-dirgibi kendi ayarı varsa onu tercih edin.- Ajanlar pencereyi yalnızca bu ortamın süreç ağacına ulaşabilen
app_useile yönetir. Ajan masaüstünü değil, pencereyi görür. Ajan başlatmaları eylem ilkesinden geçer ve varsayılan olarak sorar; bir kişi denetimi elindeyken ajan girdisi durur. "input": "background"(varsayılan) olayları sürece gönderir."foreground"pencereyi etkinleştirir ve imleci devralır.
Worktree görevleri
Bölüm başlığı “Worktree görevleri”provision ve archive görevleri, bir deponun kurulumunu ve sökümünü worktree’siyle birlikte çalıştırır. Ayarlar → Çalışma alanı → Depolar bölümünde bir deponun satırındaki simge, deponun tanımını açar.
Bu görevler ortamı değil worktree’yi izler, bu yüzden kimsenin Başlat düğmesine basmadığı alanlarda da çalışır:
provision |
archive |
|
|---|---|---|
| Çalışır | Rolün worktree’si oluşturulduğunda, herhangi bir alanda | O worktree yok edilmeden hemen önce |
| Hata durumunda | Hazırlama başarısız olur ve worktree yok edilir | Kaydedilir, silmeyi asla engellemez |
| Varsayılan zaman aşımı | 5 dakika | 2 dakika |
| Görür | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Aynısı |
Yığını olmayan bir deponun yalnızca görevlerini içeren bir tanıma ihtiyacı vardır. Başlatılacak bir şey olmadığından çapa rolü gerekmez:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Henüz ortam yoktur, bu yüzden bu görevler
{name},{port.*},{url.*},{opt.*}veyaenabledWhenkullanamaz ve tanımınenvdeğerini almaz. - Bir depo için
provisionvearchivegörevlerini yalnızca bir tanım içerebilir. Diğerleri onu geri kalan her şey için bağlayabilir. "when": ["provision", "change"]bir kilit dosyası değiştiğinde de yeniden kurar.- Bir görev kendi
cwdrolünün worktree’si için çalışır, bu yüzden çok depolu bir tanım her depoyu ayrı ayrı kurabilir. - Test çalıştırması
CC_SCRIPT_TEST=1ayarlar. Yeniden deneme temiz bir worktree’den başlar, bu yüzden yeniden çalıştırmaya dayanan görevler yazın.
Ajanlar
Bölüm başlığı “Ajanlar”Ajanlar Docker soketini asla almaz. Uygun bir tanımı olan alanda bir çalıştırma, kendi PATH yolunda cc-env alır. Alan çalıştırmadan gelir, bu yüzden bir ajan yalnızca kendi ortamında işlem yapabilir ve her komut eylem ilkesinden geçer.
cc-env statuscc-env upcc-env downcc-env resetcc-env destroycc-env restart <process>cc-env logs <name>cc-env exec <service> -- <cmd>cc-env run <task> -- <args>Bir compose bileşeniyle, bir docker shim’i ps, logs, exec, port, restart ve top ile docker compose kullanımına da izin verir, yalnızca bu ortamın kendi compose projesine karşı. Fiilden önce bayrak gelemez ve her fiil kısa bir seçenek listesi alır: logs izlenemez, exec yalnızca -T (ya da --no-tty) alır. Compose’u başka bir dosyaya ya da projeye yönlendiren seçenekler (-f, -p, --project-directory, --env-file, --profile) nerede görünürse görünsün reddedilir. Diğer her şey 5 koduyla ve “not available in Control Center agent runs” iletisiyle çıkar.
Skill’leri kendi aracını çağıran bir depo bunu sürdürebilir. Bir cli bileşenindeki agentPassthrough bloğu, ajanların hangi komutları çalıştırabileceğini bildirir. Yalnızca onaylanmış tanımın bildirdiği komutlar geçer ve her biri ana makinede çalıştığı için Ana makinede komut çalıştır kuralını taşır; bu kural varsayılan olarak önce sorar:
"agentPassthrough": { "binary": "acme", "allow": [ { "argv": ["env", "ls"], "maps": "status", "nameFilter": true }, { "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 }, { "argv": ["env", "create"], "maps": "up", "positionalName": 2, "pathFlags": ["--web-dir"], "denyFlags": ["--force"] }, { "argv": ["env", "logs"], "maps": "logs", "positionalName": 2, "denyFlags": ["--follow"] } ]}maps, ilkesi uygulanacak işlemi adlandırır. positionalName o bağımsız değişkeni bu alanın ortamına zorlar, nameFilter JSON çıktısını ona göre süzer ve her pathFlags değeri çalıştırmanın worktree’lerinin içine çözümlenmelidir. Hiçbir kuralla eşleşmeyen komut 5 koduyla çıkar.
Aynı işlemler araç olarak da vardır: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app ve environment_stop_app. Korumalı alandaki ajanlar bağlantı noktalarına doğrudan, ortamlarının ana makine adlarına ise çalıştırmanın proxy’si üzerinden ulaşır; bu yüzden onlara URL tahmin etmek yerine uç noktaları environment_status çıktısından okumalarını söyleyin.
Fork pull request’leri
Bölüm başlığı “Fork pull request’leri”Bir fork PR’ının koduna güvenilmez ve ana makine yerleşiminde sunucunun işletim sistemi kullanıcısı olarak çalışır. Ne olacağına policy.forkPrs karar verir:
| Değer | Etki | Varsayılan olduğu yer |
|---|---|---|
rig |
Compose dosyası sormadan bir VM’de çalışır | Yalnızca compose ve task bileşenleri olan tanımlar |
approval |
Her başlatma bir yönetici gerektirir | Diğer tüm tanımlar |
deny |
Reddedilir | Hiçbiri |
seedFilesbir fork için asla kopyalanmaz, çünkü genellikle gizli bilgilerdir. Bunlardan birini bağlayan bir compose dosyası eksik dosyayı adıyla bildirir.provisionvearchivegörevleri atlanır; ilkerigise VM’de çalışırlar.- Ana makine yerleşiminde bir fork’ta
privileged, ana makine ad alanları, Docker soketi bağlaması,devicesve alanın worktree’leri dışındaki bağlamalar reddedilir. Güvenilir alanlarda yalnızca uyarı verirler.
Rig yerleşimi
Bölüm başlığı “Rig yerleşimi”"placement": "rig", compose ve task bileşenlerini ayrılmış bir microVM içinde çalıştırır. process, cli veya app bileşenleri olan tanımlar uygun değildir. Compose dosyası değiştirilmeden, ana makinenin Docker soketi ve işletmeci kimlik bilgileri olmadan çalışır; ağ erişimi imajlarının ihtiyaç duyduğu kayıt defterleriyle sınırlıdır. Worktree canlı olarak bağlanır.
- arm64 konuklar. Konuklar Apple Silicon’da arm64’tür, bu yüzden yalnızca amd64 imajlar çalışmaz.
- Özel kayıt defterleri reddedilir. Konuklarda kayıt defteri kimlik bilgisi yoktur, bu yüzden bilinen genel kayıt defterleri dışındaki bir imaj VM açılmadan önce reddedilir. Genel bir kayıt defterindeki özel depo, konuk onu çektiğinde başarısız olur.
- 16 GiB depolama. Yığının tüm imajları ve birimleri tek bir 16 GiB diski paylaşır ve bu artırılamaz.
- İlk açılış yavaştır. İmaj katmanları VM başınadır, bu yüzden ilk açılış her şeyi çeker. Durdurulmuş bir rig diskini korur.
- Temel imajlar okunabilir olmalıdır. Temel imajını bir değişkenle adlandıran bir Dockerfile planlanamaz, çünkü ağ erişimi açılışta sabitlenir.
- Ömür.
policy.rigTtlHoursVM’yi sonlandırır, varsayılan olarak 24 saat sonra.
Araç yazarları için durum sözleşmesi
Bölüm başlığı “Araç yazarları için durum sözleşmesi”statusMap içermeyen bir cli bileşeni yerel sözleşmeyi, yani cc-env/1 biçimini bekler. status fiili bu nesneyi stdout’a yazdırır:
{ "state": "ready", "detail": "migrations applied, HTTP 200", "endpoints": [ { "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true }, { "role": "postgres", "label": "Postgres", "hostPort": 49213 } ], "services": ["server", "postgres"], "needsRecreate": false, "error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }}statedeğeriready,starting,stopped,failedveyamissingolur.missing,createişlemine;stoppedvefailed,startişlemine götürür.missingdurumunu 0 çıkış koduyla bildirin: başarısız birstatus,failedsayılır.- Yalnızca
stategereklidir. Bilinmeyen alanlar yok sayılır, ayrıştırılamayan çıktı ise ham metin ayrıntı olacak şekilde bozulmuş olarak görünür. - URL, loopback,
*.localhostveyarouting.domainaltında olmalıdır; aksi halde atılır. needsRecreate: true, verileri atan Yeniden oluştur seçeneğini gösterir. Control Center buna göre asla kendiliğinden işlem yapmaz.listfiili, adlardan veyanameiçeren nesnelerden oluşan bir JSON dizisi yazdırır.
Çıkış kodları her fiil için geçerlidir:
| Kod | Anlam |
|---|---|
| 0 | Tamam |
| 3 | Bir terminalde yanıt gerekir, örneğin bir sudo parolası. interactive içinde listelenen bir fiil, Başlat düğmesine basan kişi için bir terminal sekmesinde yeniden çalışır. Aksi halde Terminalde çalıştır, aracın command değeri yazılmış ama çalıştırılmamış bir alan terminali açar, ardından Yeniden dene yeniden dener. Control Center asla sudo çalıştırmaz ve hiçbir istemi yanıtlamaz |
| 4 | Oturum açma gerekli. Aracın command değeri nasıl yapılacağını söyler |
| 5 | Bağlı olduğu bir şey kullanılamıyor, örneğin çalışmayan bir kapsayıcı çalışma zamanı |
| Diğer | Hata |
Kodlar 3, 4 ve 5 hata değildir. Ortam İşlem gerekli gösterir ve bekler; bir sonraki başlatma, o başlatmanın durduğu yerden devam eder. Bunlardan biriyle çıkan bir görev de aynı anlama gelir.
İlerleme, satırlarla ayrılmış JSON olarak stderr’e gider:
{"type":"step","id":"images","label":"Pull images","state":"running"}{"type":"log","stream":"stdout","line":"postgres Pulled"}{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}Ortam başlarken panel, başlatmanın geçtiği bileşenleri listeler; her birinde bir dönen simge, bir onay ya da bir çarpı bulunur. Bir step satırı aracın şu anda ne yaptığını bildirir ve label değeri aracın kendi satırının altında gösterilir; adımlar hiçbir zaman yeni satır eklemez. Bir adımın state değeri pending, running, done veya failed olur; state içermeyen bir adım çalışıyor sayılır. Aynı id ile (metin ya da sayı; yoksa aynı label ile) yeniden bildirim yapan bir adım önceki sözünün yerini alır; bu sayede tek bir dönen simgesi olan bir araç aynı id’yi koruyup yalnızca label’ı değiştirebilir. Kimlik olmadan adımlar birbirini izler: yeni bir adım, öncekini bitirir. Komut çıktığında hâlâ çalışan bir adım, komutun nasıl bittiyse öyle biter.
log satırı, araçın JSON içine sardığı tek bir çıktı satırını taşır ve düz çıktı gibi okunur. note satırı çalıştırmanın çıktısına gider, "level": "warn" içerenler ise uyarı olarak ortamda da kalır. error türündeki son satır yapılandırılmış bir hataya dönüşür ve command kopyalanmak üzere sunulur, ayrıca çıktının son 12 satırı message değerinin altında gösterilir. Bu yoksa Control Center son 20 stderr satırını gösterir. JSON olmayan her şey düz günlük çıktısıdır.