Environments einrichten
Ein Environment ist der laufende Stack eines Bereichs: die Dienste, die ein Branch braucht, isoliert von allen anderen Bereichen, sichtbar in der Seitenleiste und für Agenten erreichbar. Auch Pull Requests bekommen eines, denn ein PR hat bereits seinen eigenen Bereich.
Ein Admin des Arbeitsbereichs schreibt einmal eine Definition. Mitglieder klicken dann im Abschnitt Environment der Seitenleiste eines Bereichs oder PRs auf Starten. Definitionen liegen in der Datenbank des Arbeitsbereichs, ein Feature-Branch ändert also nie, was Control Center ausführt. Die Tools führen aber weiterhin den Code dieses Branches aus.
Eine Definition anlegen
Abschnitt betitelt „Eine Definition anlegen“- Öffne Einstellungen → Arbeitsbereich → Environments. Nur Admins des Arbeitsbereichs können Definitionen ändern, und nur der Serverinhaber kann eine speichern, die auf dem Server-Host läuft (siehe Wer darf was speichern).
- Klicke auf Neue Definition und dann auf Leere Definition oder Aus Repo entwerfen. Ein Entwurf durchsucht das Repo nach Compose-Dateien, einem
Procfileundpackage.json-Skripten, und du prüfst das Ergebnis. - Fülle das Formular aus oder nutze den Tab JSON. Die Beispiele auf dieser Seite zeigen dieses JSON.
- Klicke auf Test ausführen. Das startet ein Wegwerf-Environment, wartet, bis es bereit ist, und zerstört es wieder.
Speichern prüft eine Definition streng. Ein unbekanntes Feld, ein Wert mit falschem Typ oder eine falsch geschriebene Auswahl wird abgelehnt, mit Pfad und dem nächstliegenden gültigen Namen, etwa repos.app.requird: Unknown field. Did you mean "required"?. Ein $schema auf oberster Ebene ist erlaubt.
Um eine Definition in einem Repo zu pflegen, nutze Repo-Datei verknüpfen. Control Center liest die Datei nur vom Standardbranch und führt nur die Version aus, die freigegeben wurde: von einem Admin des Arbeitsbereichs oder, wenn die Definition auf dem Host läuft, vom Serverinhaber. Eine neuere Version zeigt Update verfügbar und ändert bis zur Freigabe nichts.
Wer darf was speichern
Abschnitt betitelt „Wer darf was speichern“Eine Environment-Definition kann Befehle auf dem Server-Host als dessen eigener Benutzer ausführen. Das ist die Entscheidung des Serverinhabers, nicht einer Arbeitsbereichsrolle:
- Eine Definition läuft auf dem Host, wenn sie Host-Platzierung hat, eine Prüfung, die einen Befehl ausführt, oder eine Aufgabe
provisionoderarchive. Diese Aufgaben laufen auf dem Host im Worktree des Bereichs, unabhängig von der Platzierung. - Nur der Serverinhaber kann eine Definition speichern oder genehmigen, die auf dem Host läuft. Dazu gehört auch die Genehmigung einer neuen Version einer verknüpften Repo-Datei. Ein Admin des Arbeitsbereichs, der es versucht, sieht „Nur der Serverinhaber kann eine Umgebung speichern oder genehmigen, die auf dem Server-Host läuft. Ein Workspace-Admin kann eine nutzen, die in einem Rig läuft.“
- Ein Admin des Arbeitsbereichs kann eine Definition speichern und genehmigen, die vollständig in einem Rig läuft:
"placement": "rig", ohne Prüfbefehl und ohne Aufgabeprovisionoderarchive. - Mitglieder starten, stoppen und nutzen Environments in beiden Fällen.
- Eine Definition, die auf dem Host läuft, läuft erst, nachdem der aktuelle Serverinhaber sie gespeichert oder genehmigt hat. Der Server hält diese Genehmigung selbst fest und prüft sie vor jedem Start, jeder Prüfung, jeder Aufgabe und jedem Abgleich des PR-Heads. Eine Definition, die der aktuelle Inhaber nicht genehmigt hat, etwa eine, die ein früherer Inhaber gespeichert hat, wartet unter ihrer Zeile in der Environment-Liste und im Editor. Der Serverinhaber sieht „Läuft auf diesem Server. Genehmige sie, damit sie starten kann.“ mit Genehmigen, was die Definition unverändert speichert; alle anderen sehen „Läuft auf diesem Server. Der Serverinhaber muss sie genehmigen, bevor sie starten kann.“
- Eine Environment, die auf diese Genehmigung wartet, zeigt „Der Serverinhaber hat diese Umgebung noch nicht genehmigt, daher kann sie auf diesem Server nicht laufen.“ Der Serverinhaber sieht stattdessen „Du hast diese Umgebung noch nicht genehmigt. Sie läuft auf diesem Server und startet, sobald du ihre Definition genehmigst.“ mit Prüfen und genehmigen, was die Definition öffnet.
- Prozess-Terminals einer Environment und das Terminal, das ein Start öffnet, wenn er dich braucht, laufen auf dem Server-Host. Tippen, Größe ändern oder Schließen braucht Schreibzugriff auf jedes Repository, das der Bereich freigibt und das über deine eigene Forge-Anmeldung lesbar ist; das gilt wie beim Starten der Environment. Alle anderen erreichen diese Terminals gar nicht.
Die kleinste Definition
Abschnitt betitelt „Die kleinste Definition“Ein einfaches Compose-Repo braucht nur das:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Alles andere hat einen Standardwert: Die Compose-Datei wird gefunden, jeder Dienst läuft, Ports werden zugewiesen, HTTP-Endpunkte werden erkannt, und das Environment heißt wie der Branch.
Komponentenarten
Abschnitt betitelt „Komponentenarten“Ein Environment ist eine geordnete Liste von Komponenten. Jede wartet, bis die vorherige bereit ist, sofern after keine anderen nennt, und das Stoppen läuft umgekehrt. enabledWhen macht eine Komponente von einer Option oder Rolle abhängig, zum Beispiel opt.seed, !opt.seed oder repo.web. Eine Komponente, deren Rolle optional und im Bereich nicht vorhanden ist, wird genauso ausgelassen, ohne dass enabledWhen nötig ist: Sie startet nicht und hat weder {port.*} noch {url.*}, sodass eine andere Komponente, die diese liest, den Start scheitern lässt.
| Art | Wer sie ausführt | Wofür |
|---|---|---|
compose |
Der Compose-Treiber von Control Center | Jede Compose-Datei, eine pro Environment |
cli |
Dein Tool. Control Center ruft zugeordnete Verben auf und liest JSON | Ein Tool, dem Lebenszyklus, Domains und Daten gehören |
process |
Control Center, in einer überwachten Terminalsitzung | Dev-Server und Worker |
task |
Control Center, einmal pro Auslöser | Installationen, Migrationen, Tests |
app |
Control Center, wenn jemand auf Starten klickt | Eine Desktop-App |
task-Komponenten nehmen eine when-Liste:
| Auslöser | Läuft |
|---|---|
provision |
Wenn der Worktree erstellt wird (siehe Worktree-Tasks unten) |
create |
Einmal pro Environment und erneut nach einem Zurücksetzen |
start |
Bei jedem Start |
change |
Nach einem Sync, wenn ein geänderter Pfad zu onChange passt |
manual |
Auf Anfrage: Ausführen, cc-env run <id> oder environment_run_task |
archive |
Kurz bevor der Worktree zerstört wird |
Eine Task, die beim Start nichts zu tun hat, zeigt Inaktiv und fehlt in der Liste der Schritte, die angezeigt werden, während die Environment startet: eine manual- oder change-Task oder eine create-Task, die bereits gelaufen ist.
Ein als Array angegebener Befehl ist argv, Optionswerte laufen also nie durch eine Shell. Ein String oder script mit einem Array von Zeilen läuft unter bash -lc. Platzhalter wie {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} und {url.<role>} werden nur in argv aufgelöst. Shell-Befehle lesen dieselben Werte als CC_ENV_*-Variablen, etwa $CC_ENV_PORT_WEB. Ein unbekannter Platzhalter in einer beteiligten Komponente stoppt den Start, bevor etwas ausgeführt wird.
Jeder Befehl und jedes Bereichsterminal bekommt außerdem CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> und in PR-Bereichen CC_PR_NUMBER und CC_PR_IS_FORK. Mit einer Compose-Komponente kommen COMPOSE_PROJECT_NAME und COMPOSE_FILE dazu, sodass docker compose exec in einem Task das richtige Projekt erreicht.
Rollen und Arbeitsverzeichnis
Abschnitt betitelt „Rollen und Arbeitsverzeichnis“Eine Definition bindet Rollen an Repos des Arbeitsbereichs, sodass ein Stack mehrere Repos umfassen kann:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: Ein Bereich kann das Environment starten, wenn er mindestens eine Anker-Rolle enthält. Passen zwei Definitionen, wählt die Person, die startet.required: Der Stack läuft ohne dieses Repo nicht.whenMissing: Was passiert, wenn dem Bereich die Rolle fehlt.addToSpacefügt das Repo auf seinem Standardbranch hinzu und ist der Standard fürrequired-Rollen.useSourceübergibt deinen registrierten Checkout, den du als schreibgeschützt behandeln solltest.skiplässt die Variable leer und ist sonst der Standard.- Zum Starten brauchst du eine
write-Berechtigung auf einem Anker-Repo im Bereich und Lesezugriff auf jedes andere gebundene Repo.
Ein Befehl läuft in der ersten in repos deklarierten Rolle, nie in einer anderen Rolle, die der Bereich zufällig hat, eine Definition mit einem Repo erwähnt das also nie. Jede Komponente kann das mit "cwd": { "role": "e2e", "path": "packages/ui" } überschreiben. Beide Felder sind optional. Wenn die erste Rolle in einem Bereich fehlen könnte, weil sie weder required noch der einzige Anker ist, muss jede Komponente ihre Rolle nennen.
Ports und URLs
Abschnitt betitelt „Ports und URLs“Control Center weist Host-Ports zu, bevor etwas startet, aus einem hostweiten Bereich (standardmäßig 42000 bis 49999, in Blöcken von 32). Ein Port bleibt für die Lebensdauer des Environments gleich, und Compose-Ports binden nur an 127.0.0.1.
- Compose-Ports müssen nicht deklariert werden. Lies sie als
{port.postgres.5432}oderCC_ENV_PORT_POSTGRES_5432. - Andere Ports werden dort deklariert, wo sie gebraucht werden, mit
"port": "web"oder"ports": ["web", "hmr"], und als{port.web}gelesen. Ein Prozess mit Port bekommt außerdemPORTundHOST=127.0.0.1.
HTTP-Endpunkte bekommen eine URL auf dem Router des Servers, der auf einem Loopback-Port lauscht:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>ist der Branch als Slug oderpr-<n>in einem PR-Bereich.<project>istnaming.project, sonst der Name der Definition.*.localhost-Namen zeigen auf Loopback, sie brauchen also weder Hosts-Einträge noch DNS, und der Hostname hält Cookies zwischen Environments getrennt.- Compose-Ports, die HTTP sprechen, werden erkannt, und
httpan der Komponente überschreibt die Vermutung. Ein Prozess braucht"endpoint": { "role": "web", "primary": true }, das auch{url.web}verfügbar macht. - Im Browser (VM) nutze Im Browser (VM) öffnen.
https://web--fix-login--shop.localhost/erreicht dort dieselbe Route. - Das gesamte Label bleibt innerhalb von 63 Zeichen, lange Namen werden also mit einem Hash gekürzt.
- Zwei Endpunkte teilen keine übergeordnete Domain. Eine App, die ein Cookie über beide braucht, muss sie von einem Endpunkt ausliefern.
Für URLs, die du vorab registrieren musst, etwa OAuth-Redirects, liefert "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } eine feste Menge von Namen.
policy legt fest, wann Environments laufen. autoCreate ist off, prSpaces oder allSpaces, idleStopMinutes ist standardmäßig 240, followPrHead synchronisiert ein PR-Environment, wenn sich sein Head bewegt, und bei maxRunning (Standard 6) bietet Starten an, das am längsten ungenutzte Environment zu stoppen.
Beispiel: Compose-App
Abschnitt betitelt „Beispiel: Compose-App“Eine Web-App und Postgres aus einer Compose-Datei, mit einer gitignorierten .env, Migrationen und einem Test-Task. seedFiles kopiert benannte Dateien aus deinem registrierten Checkout in jeden neuen Worktree.
{ "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" } ]}Mit healthchecks kann auch ein Dienst ohne eigenen Healthcheck die nächste Komponente aufhalten. Ohne ihn gilt ein laufender Container als bereit, und Migrationen können einer noch startenden Datenbank zuvorkommen.
Jeder Start und jede Aktualisierung führt up mit --remove-orphans aus, sodass ein Dienst, der aus der Compose-Datei entfernt wurde, stoppt und seinen Port freigibt. Images werden beim Start und bei der Aktualisierung gebaut, außer die Komponente setzt "build": false.
Beispiel: eigene CLI
Abschnitt betitelt „Beispiel: eigene CLI“Ein erfundenes Tool acme, dem seine Container, Domains und TLS gehören. Control Center liefert {name} und erfährt alles andere aus status. Es leitet nie die Hostnamen eines Tools ab und bearbeitet nie /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,statusunddestroysind Pflicht. Control Center wähltcreateoderstartanhand des gelesenen Status. Jedes Verb kann statt argv auch{ "shell": "…" }sein.interactivenennt die Verben auscreate,startundreset, die ihre benötigten Angaben an einem Terminal erfragen können. Beendet sich ein solches Verb mit Code 3 für eine Person, die Starten gedrückt hat, führt Control Center dasselbe Verb erneut in einem Terminal-Tab aus, und der Start läuft weiter, sobald es mit 0 endet. Dort ist die Bedingunginteractivewahr undCC_ENV_INTERACTIVE=1gesetzt, sodass{ "if": "!interactive", "args": ["--json"] }die maschinelle Ausgabe für die nicht interaktive Ausführung beibehält. Ein Start durch einen Agenten oder ein automatischer Start öffnet nie ein Terminal: Die Environment zeigt Aktion nötig und wartet.- Ein
destroy, das fehlschlägt, entfernt die Environment trotzdem, wennstatusdanachmissingmeldet, sodass eine Environment, die das Tool nicht mehr hat, immer entfernt werden kann. listlässt Control Center eine Environment bemerken, die das Tool verloren hat. Sie gilt nur dann als verschwunden, wenn ihr Name inlistfehlt undstatusdannmissingmeldet. Ausgabe, die sich nicht als Liste lesen lässt, ändert nichts.{service}inlogsundexecmuss ein einzelnes Wort sein, das nicht mit-beginnt, und einer der Dienste, die das Tool zuletzt gemeldet hat, sofern es welche gemeldet hat.statusMapliest das eigene JSON des Tools mit JSON-Pointern, wobei*auf jedes Element passt. Zustandsregeln sind geordnet, und der erste Treffer gewinnt. Eine Bedingung istpathmitequalsoderanybzw.nonemitwhere.keepsDataOnStop: falseschaltet den Leerlauf-Stopp aus und ergänzt Stoppen um eine Warnung vor Datenverlust. Setze es, wenn beim Stoppen Daten verloren gehen.routing.mode: "tool"verbindet die Hostnamen des Tools mit dem Browser (VM) und mit Agenten. Die Domain muss auf.test,.localhostoder.internalenden, und eine gemeldete URL außerhalb davon wird verworfen.
Ein Tool, das dir gehört, kann statusMap weglassen und den Statusvertrag ausgeben, der am Ende dieser Seite beschrieben ist.
Beispiel: pnpm-Monorepo
Abschnitt betitelt „Beispiel: pnpm-Monorepo“Nur Prozesse und Tasks, keine Container. Die Web-App findet die API über {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"] } ]}- Jeder Prozess ist ein Terminal-Tab, den du öffnen, lesen und in den du tippen kannst, wenn du Schreibzugriff auf jedes Repository im Bereich hast (siehe Wer darf was speichern). Das Schließen des Tabs stoppt ihn nicht.
readynimmthttp(eine vollständige URL),tcp(host:port) oderlogMatch(ein regulärer Ausdruck).restartiston-failure(der Standard),alwaysodernever.restartOnstartet den Prozess neu, wenn ein geänderter Pfad passt.optionswerden zu einem Formular bei Starten, undagentDefaultgilt für Läufe, die ein Agent startet.
Beispiel: Desktop-App
Abschnitt betitelt „Beispiel: Desktop-App“Eine Desktop-App mit Build-Schritt. Eine App funktioniert gleich, egal womit sie gebaut ist, denn Control Center arbeitet auf Ebene der Betriebssystemfenster und braucht keinen Hook und kein SDK in der App.
{ "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" } ]}Eine App startet nicht mit dem Environment. Jemand klickt auf Starten, und prepare läuft zuerst. Neu bauen und starten führt dieses Paar erneut aus. enabledWhen gilt für die App und ihre prepare-Aufgabe, und Starten wird abgelehnt, solange eines von beiden deaktiviert ist. Eine App gilt als laufend, solange ein Prozess ihrer Prozessgruppe läuft, sodass ein Starter, der die App startet und sich dann beendet, in Ordnung ist. Ist innerhalb von etwa 5 Sekunden nach Starten alles verschwunden, zeigt die App einen Fehler mit ihren letzten Logzeilen. Danach wird ein sauberes Beenden als geschlossen angezeigt und ein Absturz zeigt die letzten Logzeilen, und keines von beiden startet sie neu. Ein Serverneustart schließt die App und startet sie nie neu, und der Leerlauf-Stopp lässt eine laufende App in Ruhe.
Berechtigungen und Grenzen von Desktop-Apps
Abschnitt betitelt „Berechtigungen und Grenzen von Desktop-Apps“- Gib Control Center unter macOS einmalig in den Systemeinstellungen die Rechte Bildschirmaufnahme und Bedienungshilfen. Der Server-Host braucht eine GUI-Sitzung: Ein Headless-Server verweigert den App-Start.
- Starte die Binärdatei direkt.
open -aübergibt die App an LaunchServices, und sie verlässt den Prozessbaum, den Control Center verfolgt, sodass die App direkt nach dem Start einen Fehler anzeigt. - Fenster bleiben auf einem Display. macOS erfasst kein Fenster, das außerhalb aller Displays liegt, eine von einem Agenten genutzte App ist also auf dem Bildschirm des Servers sichtbar. Sie braucht keinen Fokus.
"isolate": "home"gibt der App überHOME,XDG_*undCFFIXED_USER_HOMEein privates Home, sodass Kopien aus zwei Bereichen nebeneinander laufen können.NSUserDefaultsist nicht isoliert, Cocoa-Einstellungen und Fluttersshared_preferencesbleiben also zwischen den Kopien geteilt.isolategilt nur für den gestarteten Prozess. Ein Toolchain-Launcher wieflutter runbraucht das echte Home, kombiniereisolatealso mit einer gebauten Binärdatei. Hat die App eine eigene Einstellung wie--user-data-dir, nimm lieber diese.- Agenten steuern das Fenster mit
app_use, das nur den Prozessbaum dieses Environments erreicht. Ein Agent sieht das Fenster, nicht den Desktop. App-Starts durch Agenten laufen über die Aktionsrichtlinie und fragen standardmäßig nach, und Agenteneingaben pausieren, solange eine Person die Kontrolle hat. "input": "background"(der Standard) sendet Ereignisse an den Prozess."foreground"aktiviert das Fenster und übernimmt den Mauszeiger.
Worktree-Tasks
Abschnitt betitelt „Worktree-Tasks“provision- und archive-Tasks führen Setup und Abbau eines Repos mit seinem Worktree aus. Das Symbol in der Zeile eines Repos unter Einstellungen → Arbeitsbereich → Repositorys öffnet die Definition des Repos.
Diese Tasks folgen dem Worktree, nicht dem Environment, und laufen also auch in Bereichen, in denen niemand auf Starten klickt:
provision |
archive |
|
|---|---|---|
| Läuft | Wenn der Worktree der Rolle erstellt wird, in jedem Bereich | Kurz bevor dieser Worktree zerstört wird |
| Bei Fehler | Die Bereitstellung schlägt fehl und der Worktree wird zerstört | Wird protokolliert, blockiert das Löschen nie |
| Standard-Timeout | 5 Minuten | 2 Minuten |
| Sieht | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Dasselbe |
Ein Repo ohne Stack braucht nur eine Definition mit seinen Tasks. Da es nichts zu starten gibt, ist keine Anker-Rolle nötig:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Es gibt noch kein Environment, diese Tasks können also weder
{name},{port.*},{url.*},{opt.*}nochenabledWhennutzen, und sie bekommen dasenvder Definition nicht. - Nur eine Definition darf
provision- undarchive-Tasks für ein Repo enthalten. Andere dürfen es für alles Weitere trotzdem binden. "when": ["provision", "change"]installiert auch neu, wenn sich eine Lockfile ändert.- Ein Task läuft für den Worktree seiner
cwd-Rolle, eine Definition mit mehreren Repos kann also jedes Repo einzeln einrichten. - Ein Testlauf setzt
CC_SCRIPT_TEST=1. Ein erneuter Versuch beginnt mit einem sauberen Worktree, schreibe Tasks also so, dass sie eine Wiederholung überstehen.
Agenten
Abschnitt betitelt „Agenten“Agenten bekommen nie den Docker-Socket. In einem Bereich mit passender Definition bekommt ein Lauf cc-env in seinen PATH. Der Bereich ergibt sich aus dem Lauf, ein Agent kann also nur auf sein eigenes Environment zugreifen, und jeder Befehl läuft über die Aktionsrichtlinie.
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>Mit einer Compose-Komponente erlaubt ein docker-Shim außerdem docker compose mit ps, logs, exec, port, restart und top, und zwar nur gegen das eigene Compose-Projekt dieser Environment. Vor dem Verb dürfen keine Flags stehen, und jedes Verb akzeptiert eine kurze Liste von Optionen: logs kann nicht folgen, und exec akzeptiert nur -T (oder --no-tty). Optionen, die compose auf eine andere Datei oder ein anderes Projekt zeigen lassen (-f, -p, --project-directory, --env-file, --profile), werden abgelehnt, wo immer sie stehen. Alles andere endet mit Exit-Code 5 und „not available in Control Center agent runs“.
Ein Repo, dessen Skills sein eigenes Tool aufrufen, kann das weiter tun. Ein agentPassthrough-Block an einer cli-Komponente legt fest, welche Befehle Agenten ausführen dürfen. Nur Befehle, die die genehmigte Definition deklariert, werden durchgereicht, und jeder läuft auf dem Host, daher gilt für ihn die Regel Befehle auf dem Host ausführen, die standardmäßig zuerst fragt:
"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 nennt die Operation, deren Richtlinie gilt. positionalName erzwingt für dieses Argument das Environment dieses Bereichs, nameFilter filtert die JSON-Ausgabe darauf, und jeder pathFlags-Wert muss innerhalb der Worktrees des Laufs liegen. Ein Befehl, auf den keine Regel passt, endet mit Exit-Code 5.
Dieselben Operationen gibt es als Tools: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app und environment_stop_app. Sandbox-Agenten erreichen ihre Ports direkt und die Hostnamen ihres Environments über den Proxy des Laufs, weise sie also an, Endpunkte aus environment_status zu lesen, statt eine URL zu raten.
Fork-Pull-Requests
Abschnitt betitelt „Fork-Pull-Requests“Der Code eines Fork-PRs ist nicht vertrauenswürdig, und bei Host-Platzierung läuft er als Betriebssystembenutzer des Servers. policy.forkPrs entscheidet, was passiert:
| Wert | Wirkung | Standard für |
|---|---|---|
rig |
Die Compose-Datei läuft ohne Rückfrage in einer VM | Definitionen nur mit compose- und task-Komponenten |
approval |
Jeder Start braucht einen Admin | Alle anderen Definitionen |
deny |
Abgelehnt | Keine |
seedFileswerden nie für einen Fork kopiert, weil sie meist Geheimnisse enthalten. Eine Compose-Datei, die eine davon einbindet, meldet die fehlende Datei beim Namen.provision- undarchive-Tasks werden übersprungen, außer die Richtlinie istrig, dann laufen sie in der VM.- Bei Host-Platzierung werden
privileged, Host-Namespaces, ein Docker-Socket-Bind,devicesund Binds außerhalb der Worktrees des Bereichs auf einem Fork abgelehnt. In vertrauenswürdigen Bereichen gibt es nur eine Warnung.
Rig-Platzierung
Abschnitt betitelt „Rig-Platzierung“"placement": "rig" führt compose- und task-Komponenten in einer eigenen microVM aus. Definitionen mit process-, cli- oder app-Komponenten kommen nicht infrage. Die Compose-Datei läuft unverändert, ohne Docker-Socket des Hosts und ohne Betreiber-Zugangsdaten, und der Netzwerkzugriff beschränkt sich auf die Registrys, die ihre Images brauchen. Der Worktree wird live eingehängt.
- arm64-Gäste. Gäste sind auf Apple Silicon arm64, reine amd64-Images laufen also nicht.
- Private Registrys werden abgelehnt. Gäste haben keine Registry-Zugangsdaten, ein Image auf einer Registry außerhalb der bekannten öffentlichen wird also abgelehnt, bevor die VM bootet. Ein privates Repository auf einer öffentlichen Registry scheitert, wenn der Gast es zieht.
- 16 GiB Speicher. Alle Images und Volumes des Stacks teilen sich eine 16-GiB-Disk, und sie lässt sich nicht vergrößern.
- Der erste Boot ist langsam. Image-Layer gelten pro VM, der erste Boot zieht also alles. Ein gestopptes Rig behält seine Disk.
- Basis-Images müssen lesbar sein. Ein Dockerfile, das sein Basis-Image über eine Variable benennt, lässt sich nicht planen, weil der Netzwerkzugriff beim Boot feststeht.
- Lebensdauer.
policy.rigTtlHoursbeendet die VM, standardmäßig nach 24 Stunden.
Statusvertrag für Tool-Autoren
Abschnitt betitelt „Statusvertrag für Tool-Autoren“Eine cli-Komponente ohne statusMap erwartet den nativen Vertrag cc-env/1. Das Verb status gibt dieses Objekt auf stdout aus:
{ "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": "…" }}stateistready,starting,stopped,failedodermissing.missingführt zucreate,stoppedundfailedführen zustart. Meldemissingmit Exit-Code 0: Ein fehlgeschlagenesstatuszählt alsfailed.- Nur
stateist nötig. Unbekannte Felder werden ignoriert, und nicht parsebare Ausgabe erscheint als beeinträchtigt, mit dem Rohtext als Detail. - Eine URL muss Loopback,
*.localhostoder unterrouting.domainsein, sonst wird sie verworfen. needsRecreate: truezeigt Neu erstellen, was Daten verwirft. Control Center handelt nie allein deswegen.- Das Verb
listgibt ein JSON-Array von Namen oder von Objekten mit einemnameaus.
Exit-Codes gelten für jedes Verb:
| Code | Bedeutung |
|---|---|
| 0 | OK |
| 3 | Eine Antwort wird an einem Terminal benötigt, etwa ein sudo-Passwort. Ein in interactive aufgeführtes Verb läuft für die Person, die Starten gedrückt hat, erneut in einem Terminal-Tab. Andernfalls öffnet Im Terminal ausführen ein Bereichsterminal mit dem command des Tools eingetippt, aber nicht ausgeführt, danach versucht Erneut versuchen es erneut. Control Center führt nie sudo aus und beantwortet nie eine Eingabeaufforderung |
| 4 | Anmeldung nötig. Der command des Tools zeigt, wie |
| 5 | Etwas, wovon es abhängt, ist nicht verfügbar, etwa eine Container-Laufzeit, die nicht läuft |
| Andere | Fehler |
Die Codes 3, 4 und 5 sind keine Fehler. Die Environment zeigt Aktion nötig und wartet, und der nächste Start knüpft dort an, wo dieser aufgehört hat. Eine Aufgabe, die mit einem dieser Codes endet, bedeutet dasselbe.
Fortschritt geht als zeilenweises JSON an stderr:
{"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"}Während eine Environment startet, listet das Panel die Komponenten auf, die der Start durchläuft, jede mit einem Spinner, einem Häkchen oder einem Kreuz. Eine step-Zeile zeigt, was das Tool gerade tut, und ihr label erscheint unter der eigenen Zeile des Tools; Schritte bekommen nie eine eigene Zeile. Der state eines Schritts ist pending, running, done oder failed, und ein Schritt ohne state läuft. Ein Schritt, der sich erneut unter derselben id (einer Zeichenkette oder einer Zahl, oder demselben label, wenn keine da ist) meldet, ersetzt seine bisherige Meldung, sodass ein Tool mit einem einzigen Spinner dieselbe id behalten und das label ändern kann. Ohne IDs folgen Schritte aufeinander: Ein neuer beendet den vorherigen. Wenn der Befehl endet, endet ein noch laufender Schritt so, wie der Befehl geendet hat.
Eine log-Zeile enthält eine Ausgabezeile, die das Tool in JSON verpackt hat, und wird wie normaler Ausgabetext gelesen. Eine note-Zeile geht in die Ausgabe des Laufs, und eine mit "level": "warn" bleibt außerdem als Warnung an der Environment. Eine letzte Zeile vom Typ error wird zu einem strukturierten Fehler, wobei command zum Kopieren angeboten wird, und die letzten 12 Zeilen der Ausgabe erscheinen unter ihrer message. Ohne sie zeigt Control Center die letzten 20 stderr-Zeilen. Alles, was kein JSON ist, ist normale Logausgabe.