Configurarea mediilor
Un mediu este stack-ul în execuție al unui spațiu: serviciile de care are nevoie o ramură, izolate de toate celelalte spații, vizibile în bara laterală și accesibile agenților. Primesc unul și pull request-urile, pentru că un PR are deja propriul spațiu.
Un administrator al spațiului de lucru scrie o definiție o singură dată. Membrii apasă apoi Pornește în secțiunea Mediu din bara laterală a unui spațiu sau PR. Definițiile se află în baza de date a spațiului de lucru, așa că o ramură de funcționalitate nu schimbă niciodată ce rulează Control Center, deși instrumentele rulează în continuare codul acelei ramuri.
Crearea unei definiții
Secțiune intitulată „Crearea unei definiții”- Deschide Setări → Spațiu de lucru → Medii. Doar administratorii spațiului de lucru pot modifica definițiile, iar doar proprietarul serverului poate salva una care rulează pe gazda serverului (vezi Cine poate salva ce).
- Apasă Definiție nouă, apoi Definiție goală sau Schiță din repo. O ciornă caută în depozit fișiere compose, un
Procfileși scripturipackage.json, iar tu verifici rezultatul. - Completează formularul sau folosește fila JSON. Exemplele de pe această pagină sunt acel JSON.
- Apasă Rulează testul. Pornește un mediu de unică folosință, așteaptă să fie gata și îl distruge.
Salvarea verifică strict o definiție. Un câmp necunoscut, o valoare de tip greșit sau o opțiune scrisă greșit este refuzat, cu calea lui și numele valid cel mai apropiat, cum ar fi repos.app.requird: Unknown field. Did you mean "required"?. Un $schema de nivel superior este permis.
Pentru a păstra o definiție într-un depozit, folosește Leagă un fișier din repo. Control Center citește fișierul doar din ramura implicită și rulează doar versiunea care a fost aprobată: de un administrator al spațiului de lucru sau, când definiția rulează pe gazdă, de proprietarul serverului. O versiune mai nouă afișează Actualizare disponibilă și nu schimbă nimic până la aprobare.
Cine poate salva ce
Secțiune intitulată „Cine poate salva ce”O definiție de mediu poate rula comenzi pe gazda serverului, ca utilizatorul propriu al serverului. Decizia aparține proprietarului serverului, nu unui rol din spațiul de lucru:
- O definiție rulează pe gazdă atunci când are plasare pe gazdă, o verificare care rulează o comandă sau o sarcină
provisionoriarchive. Acele sarcini rulează în worktree-ul spațiului de pe gazdă, indiferent de plasare. - Doar proprietarul serverului poate salva sau aproba o definiție care rulează pe gazdă. Asta include aprobarea unei versiuni noi a unui fișier legat din repo. Un administrator al spațiului de lucru care încearcă vede „Doar proprietarul serverului poate salva sau aproba un mediu care rulează pe gazda serverului. Un administrator al spațiului de lucru poate folosi unul care rulează într-o stație.”
- Un administrator al spațiului de lucru poate salva și aproba o definiție care rulează în întregime într-o stație:
"placement": "rig", fără comandă de verificare și fără sarcinăprovisionsauarchive. - Membrii pornesc, opresc și folosesc mediile în ambele cazuri.
- O definiție care rulează pe gazdă pornește doar după ce proprietarul actual al serverului a salvat-o sau aprobat-o. Serverul înregistrează singur acea aprobare și o verifică înainte de fiecare pornire, verificare, sarcină și sincronizare a capului pull request-ului. O definiție pe care proprietarul actual nu a aprobat-o, cum este una salvată de un proprietar anterior, așteaptă sub rândul ei din lista de medii și în editor. Proprietarul serverului vede „Rulează pe acest server. Aprobă-l ca să poată porni.” cu Aprobă, care o salvează neschimbată; ceilalți văd „Rulează pe acest server. Proprietarul serverului trebuie să îl aprobe înainte să poată porni.”
- Un mediu reținut pentru această aprobare spune „Proprietarul serverului nu a aprobat încă acest mediu, deci nu poate rula pe acest server.” Proprietarul serverului vede în schimb „Nu ai aprobat încă acest mediu. Rulează pe acest server, deci pornește după ce aprobi definiția lui.” cu Revizuiește și aprobă, care deschide definiția.
- Terminalele de procese ale unui mediu, și terminalul pe care o pornire îl deschide când e nevoie de intervenția ta, rulează pe gazda serverului. A scrie în ele, a le redimensiona sau a le închide necesită drept de scriere pe fiecare repository pe care îl expune spațiul, citibil prin propria ta autentificare la forge: la fel ca pornirea mediului. Ceilalți nu pot ajunge deloc la aceste terminale.
Cea mai mică definiție
Secțiune intitulată „Cea mai mică definiție”Unui depozit compose simplu îi ajunge atât:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Restul are valori implicite: fișierul compose este descoperit, toate serviciile rulează, porturile sunt alocate, punctele finale HTTP sunt detectate, iar mediul primește numele ramurii.
Tipuri de componente
Secțiune intitulată „Tipuri de componente”Un mediu este o listă ordonată de componente. Fiecare așteaptă ca precedenta să fie gata, dacă after nu indică altele, iar oprirea are loc în ordine inversă. enabledWhen condiționează o componentă de o opțiune sau de un rol, de exemplu opt.seed, !opt.seed sau repo.web. O componentă al cărei rol este opțional și lipsește din spațiu este lăsată deoparte în același fel, fără să fie nevoie de enabledWhen: nu pornește și nu are {port.*} sau {url.*}, astfel că altă componentă care le citește face pornirea să eșueze.
| Tip | Cine o rulează | La ce folosește |
|---|---|---|
compose |
Driverul compose din Control Center | Orice fișier compose, unul per mediu |
cli |
Instrumentul tău. Control Center apelează verbe mapate și citește JSON | Un instrument care își gestionează ciclul de viață, domeniile și datele |
process |
Control Center, într-o sesiune de terminal supravegheată | Servere de dezvoltare și workeri |
task |
Control Center, o dată per declanșator | Instalări, migrări, teste |
app |
Control Center, când cineva apasă Lansează | O aplicație desktop |
Componentele task primesc o listă when:
| Declanșator | Când rulează |
|---|---|
provision |
La crearea worktree-ului (vezi mai jos sarcinile de worktree) |
create |
O dată per mediu și din nou după o resetare |
start |
La fiecare pornire |
change |
După o sincronizare, dacă o cale modificată se potrivește cu onChange |
manual |
La cerere: Rulează, cc-env run <id> sau environment_run_task |
archive |
Chiar înainte de distrugerea worktree-ului |
O sarcină care nu are nimic de făcut la pornire apare cu Inactiv și nu este inclusă în lista de pași afișată în timpul pornirii mediului: o sarcină manual sau change, ori o sarcină create care a rulat deja.
O comandă dată ca tablou este argv, așa că valorile opțiunilor nu trec niciodată printr-un shell. Un șir, sau script cu un tablou de linii, rulează sub bash -lc. Substituentele precum {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} și {url.<role>} se expandează doar în argv. Comenzile shell citesc aceleași valori ca variabile CC_ENV_*, de exemplu $CC_ENV_PORT_WEB. Un substituent necunoscut dintr-o componentă care participă oprește pornirea înainte ca orice să ruleze.
Fiecare comandă și terminal de spațiu primește și CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> și, în spațiile de PR, CC_PR_NUMBER și CC_PR_IS_FORK. Cu o componentă compose primesc și COMPOSE_PROJECT_NAME și COMPOSE_FILE, astfel că docker compose exec într-o sarcină ajunge la proiectul potrivit.
Roluri și director de lucru
Secțiune intitulată „Roluri și director de lucru”O definiție leagă roluri de depozitele spațiului de lucru, astfel încât un stack poate cuprinde mai multe depozite:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: un spațiu poate porni mediul dacă are cel puțin un rol ancoră. Dacă se potrivesc două definiții, alege persoana care pornește.required: stack-ul nu poate rula fără acest depozit.whenMissing: ce se întâmplă când spațiului îi lipsește rolul.addToSpaceadaugă depozitul pe ramura implicită și este valoarea implicită pentru rolurilerequired.useSourcetransmite copia ta înregistrată, pe care trebuie să o tratezi ca doar pentru citire.skiplasă variabila nesetată și este implicit în celelalte cazuri.- Pornirea necesită o permisiune
writepe un depozit ancoră din spațiu și acces de citire la toate celelalte depozite legate.
O comandă rulează în primul rol declarat în repos, niciodată într-un alt rol pe care îl are spațiul, așa că o definiție cu un singur depozit nu îl menționează niciodată. Orice componentă poate schimba asta cu "cwd": { "role": "e2e", "path": "packages/ui" }. Ambele câmpuri sunt opționale. Când primul rol ar putea lipsi dintr-un spațiu, pentru că nu este required și nici singura ancoră, fiecare componentă trebuie să își numească rolul.
Porturi și URL-uri
Secțiune intitulată „Porturi și URL-uri”Control Center alocă porturi de gazdă înainte să pornească ceva, dintr-un interval comun întregii gazde (implicit de la 42000 la 49999, în blocuri de 32). Un port rămâne același pe toată durata de viață a mediului, iar porturile compose se leagă doar la 127.0.0.1.
- Porturile compose nu trebuie declarate. Citește-le ca
{port.postgres.5432}sauCC_ENV_PORT_POSTGRES_5432. - Celelalte porturi se declară acolo unde sunt folosite, cu
"port": "web"sau"ports": ["web", "hmr"], și se citesc ca{port.web}. Un proces cu port primește șiPORTșiHOST=127.0.0.1.
Punctele finale HTTP primesc un URL pe routerul serverului, care ascultă pe un singur port loopback:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>este ramura sub formă de slug, saupr-<n>într-un spațiu de PR.<project>estenaming.project, altfel numele definiției.- Numele
*.localhostindică loopback, deci nu au nevoie de intrări hosts sau DNS, iar numele de gazdă separă cookie-urile între medii. - Porturile compose care răspund la HTTP sunt detectate, iar
httppe componentă înlocuiește această presupunere. Un proces are nevoie de"endpoint": { "role": "web", "primary": true }, care face disponibil și{url.web}. - În browser (VM), folosește Deschide în Browser (VM).
https://web--fix-login--shop.localhost/ajunge acolo la aceeași rută. - Eticheta întreagă rămâne în limita a 63 de caractere, așa că numele lungi sunt scurtate cu un hash.
- Două puncte finale nu au un domeniu părinte comun. O aplicație care are nevoie de un cookie pe ambele trebuie să le servească dintr-un singur punct final.
Pentru URL-urile care trebuie înregistrate din timp, cum sunt redirecționările OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } oferă un set fix de nume.
policy decide când rulează mediile. autoCreate este off, prSpaces sau allSpaces, idleStopMinutes are implicit 240, followPrHead sincronizează mediul unui PR când se mută head-ul, iar cu maxRunning (implicit 6) Pornește propune oprirea mediului folosit cel mai demult.
Exemplu: aplicație compose
Secțiune intitulată „Exemplu: aplicație compose”O aplicație web și Postgres dintr-un singur fișier compose, cu un .env ignorat de git, migrări și o sarcină de testare. seedFiles copiază fișiere numite din copia ta înregistrată în fiecare worktree nou.
{ "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 permite unui serviciu fără verificare proprie de sănătate să rețină componenta următoare. Fără ea, un container în execuție contează ca gata, iar migrările pot depăși o bază de date care încă pornește.
Fiecare pornire și reîmprospătare rulează up cu --remove-orphans, astfel că un serviciu scos din fișierul compose se oprește și își eliberează portul. Imaginile sunt construite la pornire și la reîmprospătare, dacă componenta nu setează "build": false.
Exemplu: CLI propriu
Secțiune intitulată „Exemplu: CLI propriu”Un instrument inventat, acme, care își gestionează containerele, domeniile și TLS-ul. Control Center oferă {name} și află restul din status. Nu deduce niciodată numele de gazdă ale unui instrument și nu editează niciodată /etc/hosts.
{ "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,statusșidestroysunt obligatorii. Control Center alegecreatesaustartdupă starea citită. Orice verb poate fi{ "shell": "…" }în loc de argv.interactivenumește verbele, dintrecreate,startșireset, care pot cere ce le trebuie la un terminal. Când un astfel de verb se termină cu codul 3 pentru o persoană care a apăsat Pornește, Control Center rulează din nou același verb într-un tab de terminal, iar pornirea continuă când acesta se termină cu codul 0. Acolo condițiainteractiveeste adevărată șiCC_ENV_INTERACTIVE=1este setat, astfel că{ "if": "!interactive", "args": ["--json"] }păstrează ieșirea pentru mașini pentru pipe. O pornire de către un agent sau una automată nu deschide niciodată un terminal: mediul arată Necesită acțiune și așteaptă.- Un
destroycare eșuează tot elimină mediul dacăstatusraportează apoimissing, astfel încât un mediu pe care instrumentul nu-l mai are poate fi întotdeauna șters. listpermite Control Center să observe un mediu pe care unealta l-a pierdut. Este marcat ca dispărut doar când numele lui lipsește dinlistșistatusatunci spunemissing. Ieșirea care nu poate fi citită ca listă nu schimbă nimic.{service}dinlogsșiexectrebuie să fie un singur cuvânt care nu începe cu-, și unul dintre serviciile raportate ultima dată de unealtă, dacă a raportat vreunul.statusMapcitește JSON-ul instrumentului cu pointeri JSON, unde*se potrivește cu fiecare element. Regulile de stare sunt ordonate și câștigă prima potrivire. O condiție estepathcuequals, sauanyorinonecuwhere.keepsDataOnStop: falsedezactivează oprirea la inactivitate și adaugă la Oprește un avertisment de pierdere a datelor. Setează-l când oprirea pierde date.routing.mode: "tool"conectează numele de gazdă ale instrumentului la browser (VM) și la agenți. Domeniul trebuie să se termine cu.test,.localhostsau.internal, iar un URL raportat în afara lui este eliminat.
Un instrument al tău poate renunța la statusMap și poate tipări contractul de stare descris la finalul acestei pagini.
Exemplu: monorepo pnpm
Secțiune intitulată „Exemplu: monorepo pnpm”Doar procese și sarcini, fără containere. Aplicația web găsește API-ul prin {url.api}.
{ "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"] } ]}- Fiecare proces este o filă de terminal pe care o poți deschide, citi și în care poți scrie, dacă ai drept de scriere pe fiecare repository din spațiu (vezi Cine poate salva ce). Închiderea filei nu îl oprește.
readyacceptăhttp(un URL complet),tcp(host:port) saulogMatch(o expresie regulată).restartesteon-failure(implicit),alwayssaunever.restartOnrepornește procesul când se potrivește o cale modificată.optionsdevin un formular la Pornește, iaragentDefaultse aplică rulărilor pornite de un agent.
Exemplu: aplicație desktop
Secțiune intitulată „Exemplu: aplicație desktop”O aplicație desktop cu un pas de compilare. O aplicație funcționează la fel indiferent de tehnologie, pentru că Control Center lucrează la nivelul ferestrelor sistemului de operare și nu are nevoie de hook sau SDK în aplicație.
{ "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" } ]}O aplicație nu pornește odată cu mediul. Cineva apasă Lansează, iar prepare rulează mai întâi. Recompilează și relansează rulează din nou această pereche. enabledWhen se aplică aplicației și sarcinii ei prepare, iar Lansează este refuzat cât timp oricare dintre ele este oprită. O aplicație este considerată în rulare cât timp rulează orice proces din grupul ei de procese, așa că un lansator care pornește aplicația și iese este în regulă. Dacă totul dispare în aproximativ 5 secunde de la Lansează, aplicația apare ca eșuată, cu ultimele linii de jurnal. După aceea, o ieșire curată apare ca închisă și un crash arată ultimele linii de jurnal, iar niciuna dintre acestea nu o repornește. O repornire a serverului închide aplicația și nu o relansează niciodată, iar oprirea la inactivitate lasă în pace o aplicație care rulează.
Permisiunile și limitele aplicațiilor desktop
Secțiune intitulată „Permisiunile și limitele aplicațiilor desktop”- Pe macOS, acordă o dată aplicației Control Center Înregistrare ecran și Accesibilitate în Configurări sistem. Gazda serverului are nevoie de o sesiune grafică: un server headless refuză să lanseze o aplicație.
- Lansează direct binarul.
open -apredă aplicația către LaunchServices și aceasta iese din arborele de procese urmărit de Control Center, așa că aplicația apare ca eșuată imediat după lansare. - Ferestrele rămân pe un ecran. macOS nu capturează o fereastră plasată în afara tuturor ecranelor, așa că o aplicație folosită de un agent este vizibilă pe ecranul serverului. Nu are nevoie de focus.
"isolate": "home"oferă aplicației un director personal privat prinHOME,XDG_*șiCFFIXED_USER_HOME, astfel încât copii din două spații pot rula în paralel.NSUserDefaultsnu este izolat, așa că preferințele Cocoa șishared_preferencesdin Flutter rămân comune între copii.isolatese aplică doar procesului lansat. Un lansator de toolchain precumflutter runare nevoie de directorul personal real, așa că asociazăisolatecu un binar compilat. Dacă aplicația are o setare proprie, cum e--user-data-dir, preferă-o.- Agenții controlează fereastra cu
app_use, care ajunge doar la arborele de procese al acestui mediu. Un agent vede fereastra, nu desktopul. Lansările agenților trec prin politica de acțiuni și implicit cer confirmare, iar intrarea agentului se oprește cât timp o persoană are controlul. "input": "background"(implicit) trimite evenimente către proces."foreground"activează fereastra și preia cursorul.
Sarcini de worktree
Secțiune intitulată „Sarcini de worktree”Sarcinile provision și archive rulează configurarea și demontarea unui depozit împreună cu worktree-ul lui. Pictograma de pe rândul unui depozit din Setări → Spațiu de lucru → Depozite o deschide.
Aceste sarcini urmează worktree-ul, nu mediul, așa că rulează în spații unde nimeni nu apasă Pornește:
provision |
archive |
|
|---|---|---|
| Rulează | La crearea worktree-ului rolului, în orice spațiu | Chiar înainte de distrugerea acelui worktree |
| La eșec | Provizionarea eșuează și worktree-ul este distrus | Înregistrat, nu blochează niciodată ștergerea |
| Timp limită implicit | 5 minute | 2 minute |
| Vede | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
La fel |
Un depozit fără stack are nevoie doar de o definiție cu sarcinile lui. Neavând ce porni, nu necesită rol ancoră:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Nu există încă un mediu, așa că aceste sarcini nu pot folosi
{name},{port.*},{url.*},{opt.*}sauenabledWhenși nu primescenvdin definiție. - O singură definiție poate avea sarcini
provisionșiarchivepentru un depozit. Celelalte îl pot lega în continuare pentru orice altceva. "when": ["provision", "change"]reinstalează și când se schimbă un fișier de blocare.- O sarcină rulează pentru worktree-ul rolului ei
cwd, așa că o definiție cu mai multe depozite poate configura fiecare depozit separat. - O rulare de test setează
CC_SCRIPT_TEST=1. O reîncercare pornește de la un worktree curat, așa că scrie sarcini care suportă o nouă rulare.
Agenții nu primesc niciodată socketul Docker. Într-un spațiu cu o definiție eligibilă, o rulare primește cc-env în PATH. Spațiul vine din rulare, așa că un agent poate acționa doar asupra propriului mediu, iar fiecare comandă trece prin politica de acțiuni.
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>Cu o componentă compose, un shim docker permite și docker compose cu ps, logs, exec, port, restart și top, și doar față de proiectul compose propriu al acestui mediu. Înainte de verb nu pot exista flaguri, iar fiecare verb acceptă o listă scurtă de opțiuni: logs nu poate urmări ieșirea, iar exec acceptă doar -T (sau --no-tty). Opțiunile care îndreaptă compose spre alt fișier sau alt proiect (-f, -p, --project-directory, --env-file, --profile) sunt refuzate oriunde ar apărea. Orice altceva se încheie cu codul 5 și „not available in Control Center agent runs”.
Un depozit ale cărui skill-uri apelează propriul instrument poate continua așa. Un bloc agentPassthrough pe o componentă cli declară ce comenzi pot rula agenții. Doar comenzile declarate de definiția aprobată trec prin, iar fiecare rulează pe gazdă, deci respectă regula Rulează comenzi pe gazdă, care cere confirmare implicit:
"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 numește operația a cărei politică se aplică. positionalName forțează acel argument la mediul acestui spațiu, nameFilter filtrează ieșirea JSON pentru el, iar fiecare valoare pathFlags trebuie să se rezolve în interiorul worktree-urilor rulării. O comandă care nu se potrivește cu nicio regulă se încheie cu codul 5.
Aceleași operații există ca instrumente: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app și environment_stop_app. Agenții din sandbox ajung direct la porturile lor și la numele de gazdă ale mediului prin proxy-ul rulării, așa că spune-le să citească punctele finale din environment_status în loc să ghicească un URL.
Pull request-uri din fork-uri
Secțiune intitulată „Pull request-uri din fork-uri”Codul unui PR dintr-un fork nu este de încredere, iar la plasarea pe gazdă rulează ca utilizatorul de sistem al serverului. policy.forkPrs decide ce se întâmplă:
| Valoare | Efect | Implicit pentru |
|---|---|---|
rig |
Fișierul compose rulează într-o VM, fără întrebare | Definițiile doar cu componente compose și task |
approval |
Fiecare pornire necesită un administrator | Toate celelalte definiții |
deny |
Refuzat | Niciuna |
seedFilesnu sunt niciodată copiate pentru un fork, pentru că de obicei sunt secrete. Un fișier compose care montează unul raportează fișierul lipsă pe nume.- Sarcinile
provisionșiarchivesunt omise, cu excepția cazului în care politica esterig, când rulează în VM. - La plasarea pe gazdă,
privileged, spațiile de nume ale gazdei, montarea socketului Docker,devicesși montările din afara worktree-urilor spațiului sunt refuzate pe un fork. În spațiile de încredere generează doar un avertisment.
Plasare în rig
Secțiune intitulată „Plasare în rig”"placement": "rig" rulează componentele compose și task într-o microVM dedicată. Definițiile cu componente process, cli sau app nu sunt eligibile. Fișierul compose rulează nemodificat, fără socketul Docker al gazdei și fără credențialele operatorului, iar accesul la rețea este limitat la registrele de care au nevoie imaginile. Worktree-ul este montat direct.
- Oaspeți arm64. Oaspeții sunt arm64 pe Apple Silicon, așa că imaginile doar amd64 nu rulează.
- Registrele private sunt refuzate. Oaspeții nu au credențiale de registru, așa că o imagine dintr-un registru din afara celor publice cunoscute este refuzată înainte de pornirea VM. Un depozit privat dintr-un registru public eșuează când oaspetele îl descarcă.
- 16 GiB de stocare. Toate imaginile și volumele stack-ului împart un disc de 16 GiB, care nu poate fi mărit.
- Prima pornire este lentă. Straturile de imagine sunt per VM, așa că prima pornire descarcă totul. Un rig oprit își păstrează discul.
- Imaginile de bază trebuie să poată fi citite. Un Dockerfile care își numește imaginea de bază printr-o variabilă nu poate fi planificat, pentru că accesul la rețea se fixează la pornire.
- Durată de viață.
policy.rigTtlHoursîncheie VM-ul, implicit după 24 de ore.
Contractul de stare pentru autorii de instrumente
Secțiune intitulată „Contractul de stare pentru autorii de instrumente”O componentă cli fără statusMap așteaptă contractul nativ, cc-env/1. Verbul status tipărește acest obiect pe stdout:
{ "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": "…" }}stateesteready,starting,stopped,failedsaumissing.missingduce lacreate, iarstoppedșifailedduc lastart. Raporteazămissingcu codul de ieșire 0: unstatuseșuat contează cafailed.- Este necesar doar
state. Câmpurile necunoscute sunt ignorate, iar ieșirea care nu poate fi analizată apare ca degradată, cu textul brut ca detaliu. - Un URL trebuie să fie loopback,
*.localhostsau subrouting.domain, altfel este eliminat. needsRecreate: trueafișează Recreează, care elimină datele. Control Center nu acționează niciodată singur pe baza acestui câmp.- Verbul
listtipărește un tablou JSON de nume, sau de obiecte cu unname.
Codurile de ieșire se aplică tuturor verbelor:
| Cod | Semnificație |
|---|---|
| 0 | OK |
| 3 | Este nevoie de un răspuns într-un terminal, cum ar fi o parolă pentru sudo. Un verb listat în interactive rulează din nou într-un tab de terminal pentru persoana care a apăsat Pornește. Altfel, Rulează în terminal deschide un terminal de spațiu cu command al uneltei scris, dar nerulat, apoi Reîncearcă încearcă din nou. Control Center nu rulează niciodată sudo și nu răspunde niciodată unei solicitări |
| 4 | Este necesară autentificarea. Câmpul command al uneltei spune cum |
| 5 | Ceva de care depinde nu este disponibil, cum ar fi un runtime de containere care nu rulează |
| Altul | Eșec |
Codurile 3, 4 și 5 nu sunt eșecuri. Mediul arată Necesită acțiune și așteaptă, iar următoarea pornire continuă de unde s-a oprit cea anterioară. O sarcină care se termină cu unul dintre ele înseamnă același lucru.
Progresul merge pe stderr ca JSON delimitat prin linii noi:
{"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"}Cât timp mediul pornește, panoul listează componentele prin care trece pornirea, fiecare cu un indicator rotitor, un semn de bifă sau o cruce. O linie step spune ce face instrumentul acum, iar label-ul ei apare sub linia proprie a instrumentului; pașii nu adaugă niciodată linii. state unui pas este pending, running, done sau failed, iar un pas fără state este în curs de rulare. Un pas care raportează din nou sub același id (un șir sau un număr, ori același label, dacă nu are unul) înlocuiește ce spunea înainte, așa că un instrument cu un singur indicator poate păstra un id și poate schimba label-ul. Fără id-uri, pașii se succed: unul nou îl încheie pe cel dinaintea lui. Când comanda se termină, un pas încă în curs se încheie în același fel în care s-a încheiat comanda.
O linie log conține o linie de ieșire pe care instrumentul a împachetat-o în JSON și se citește ca ieșire obișnuită. O linie note ajunge în ieșirea rulării, iar una cu "level": "warn" rămâne și pe mediu ca avertisment. O ultimă linie de tip error devine o eroare structurată, cu command oferit pentru copiere, iar ultimele 12 linii de ieșire apar sub message. Fără ea, Control Center arată ultimele 20 de linii din stderr. Tot ce nu este JSON este jurnal obișnuit.