Configurer des environnements
Un environnement est la pile en fonctionnement d’un espace : les services dont une branche a besoin, isolés de tous les autres espaces, visibles dans la barre latérale et accessibles aux agents. Les pull requests en ont un aussi, car une PR possède déjà son propre espace.
Un administrateur de l’espace de travail rédige une définition une seule fois. Les membres cliquent ensuite sur Démarrer dans la section Environnement de la barre latérale d’un espace ou d’une PR. Les définitions vivent dans la base de données de l’espace de travail : une branche de fonctionnalité ne change donc jamais ce que Control Center exécute, même si les outils exécutent bien le code de cette branche.
Créer une définition
Section intitulée « Créer une définition »- Ouvrez Paramètres → Espace de travail → Environnements. Seuls les administrateurs de l’espace de travail peuvent modifier les définitions, et seul le propriétaire du serveur peut enregistrer celle qui s’exécute sur l’hôte du serveur (voir Qui peut enregistrer quoi).
- Cliquez sur Nouvelle définition, puis sur Définition vierge ou Ébaucher depuis le dépôt. Un brouillon cherche dans le dépôt des fichiers compose, un
Procfileet des scriptspackage.json, puis vous vérifiez le résultat. - Remplissez le formulaire ou utilisez l’onglet JSON. Les exemples de cette page montrent ce JSON.
- Cliquez sur Lancer le test. Un environnement jetable démarre, Control Center attend qu’il soit prêt, puis le détruit.
L’enregistrement vérifie une définition de façon stricte. Un champ inconnu, une valeur d’un mauvais type ou un choix mal orthographié est refusé, avec son chemin et le nom valide le plus proche, comme repos.app.requird: Unknown field. Did you mean "required"?. Un $schema au niveau racine est autorisé.
Pour conserver une définition dans un dépôt, utilisez Lier un fichier du dépôt. Control Center lit le fichier uniquement sur la branche par défaut et n’exécute que la version approuvée par un administrateur de l’espace de travail, ou par le propriétaire du serveur lorsque la définition s’exécute sur l’hôte. Une version plus récente affiche Mise à jour disponible et ne change rien avant d’être approuvée.
Qui peut enregistrer quoi
Section intitulée « Qui peut enregistrer quoi »Une définition d’environnement peut exécuter des commandes sur l’hôte du serveur, sous le compte utilisateur du serveur. C’est une décision du propriétaire du serveur, et non un rôle de l’espace de travail :
- Une définition s’exécute sur l’hôte lorsqu’elle a un placement sur l’hôte, une vérification qui exécute une commande, ou une tâche
provisionouarchive. Ces tâches s’exécutent dans l’arbre de travail de l’espace, sur l’hôte, quel que soit le placement. - Seul le propriétaire du serveur peut enregistrer ou approuver une définition qui s’exécute sur l’hôte. Cela inclut l’approbation d’une nouvelle version d’un fichier de dépôt lié. Un administrateur de l’espace de travail qui essaie voit : « Seul le propriétaire du serveur peut enregistrer ou approuver un environnement qui s’exécute sur l’hôte du serveur. Un administrateur d’espace de travail peut utiliser un environnement qui tourne dans un rig. »
- Un administrateur de l’espace de travail peut enregistrer et approuver une définition qui s’exécute entièrement dans un rig :
"placement": "rig", sans commande de vérification ni tâcheprovisionouarchive. - Les membres démarrent, arrêtent et utilisent les environnements dans les deux cas.
- Une définition qui s’exécute sur l’hôte ne s’exécute qu’après que le propriétaire actuel du serveur l’a enregistrée ou approuvée. Le serveur enregistre lui-même cette approbation et la vérifie avant chaque démarrage, vérification, tâche et synchronisation de la tête d’une PR. Une définition que le propriétaire actuel n’a pas approuvée, comme une définition enregistrée par un précédent propriétaire, attend sous sa ligne dans la liste des environnements et dans l’éditeur. Le propriétaire du serveur voit « S’exécute sur ce serveur. Approuvez-le pour qu’il puisse démarrer. » avec Approuver, qui l’enregistre sans la modifier ; les autres voient « S’exécute sur ce serveur. Le propriétaire du serveur doit l’approuver avant qu’il puisse démarrer. »
- Un environnement retenu pour cette approbation affiche « Le propriétaire du serveur n’a pas encore approuvé cet environnement, il ne peut donc pas s’exécuter sur ce serveur. » Le propriétaire du serveur voit à la place « Vous n’avez pas encore approuvé cet environnement. Il s’exécute sur ce serveur et démarrera une fois sa définition approuvée. » avec Examiner et approuver, qui ouvre la définition.
- Les terminaux de processus d’un environnement, et le terminal qu’ouvre un démarrage lorsqu’il a besoin de vous, s’exécutent sur l’hôte du serveur. Y écrire, les redimensionner ou les fermer exige un accès en écriture à chaque dépôt exposé par l’espace, lisible avec votre propre connexion à la forge : la même condition que pour démarrer l’environnement. Les autres personnes ne peuvent pas du tout atteindre ces terminaux.
La plus petite définition
Section intitulée « La plus petite définition »Un dépôt compose simple n’a besoin que de ceci :
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Tout le reste a une valeur par défaut : le fichier compose est détecté, tous les services démarrent, les ports sont attribués, les points de terminaison HTTP sont détectés et l’environnement porte le nom de la branche.
Types de composants
Section intitulée « Types de composants »Un environnement est une liste ordonnée de composants. Chacun attend que le précédent soit prêt, sauf si after en désigne d’autres, et l’arrêt se fait dans l’ordre inverse. enabledWhen conditionne un composant à une option ou à un rôle, par exemple opt.seed, !opt.seed ou repo.web. Un composant dont le rôle est facultatif et absent de l’espace est écarté de la même façon, sans qu’il faille enabledWhen : il ne démarre pas et n’a ni {port.*} ni {url.*}, de sorte qu’un autre composant qui les lit fait échouer le démarrage.
| Type | Qui l’exécute | Usage |
|---|---|---|
compose |
Le pilote compose de Control Center | Tout fichier compose, un par environnement |
cli |
Votre outil. Control Center appelle les verbes associés et lit du JSON | Un outil qui gère son cycle de vie, ses domaines et ses données |
process |
Control Center, dans une session de terminal supervisée | Serveurs de développement et workers |
task |
Control Center, une fois par déclencheur | Installations, migrations, tests |
app |
Control Center, quand quelqu’un clique sur Lancer | Une application de bureau |
Les composants task prennent une liste when :
| Déclencheur | S’exécute |
|---|---|
provision |
À la création de l’arbre de travail (voir les tâches d’arbre de travail plus bas) |
create |
Une fois par environnement, puis de nouveau après une réinitialisation |
start |
À chaque démarrage |
change |
Après une synchronisation, si un chemin modifié correspond à onChange |
manual |
À la demande : Exécuter, cc-env run <id> ou environment_run_task |
archive |
Juste avant la destruction de l’arbre de travail |
Une tâche qui n’a rien à faire au démarrage affiche Inactif et n’apparaît pas dans la liste des étapes affichée pendant le démarrage de l’environnement : une tâche manual ou change, ou une tâche create déjà exécutée.
Une commande donnée sous forme de tableau est un argv : les valeurs d’option ne passent donc jamais par un shell. Une chaîne, ou script avec un tableau de lignes, s’exécute sous bash -lc. Les paramètres fictifs comme {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} et {url.<role>} ne sont développés que dans l’argv. Les commandes shell lisent les mêmes valeurs dans des variables CC_ENV_*, comme $CC_ENV_PORT_WEB. Un paramètre fictif inconnu dans un composant retenu pour cet espace arrête le démarrage avant que quoi que ce soit ne s’exécute.
Chaque commande et chaque terminal d’espace reçoivent aussi CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> et, dans les espaces de PR, CC_PR_NUMBER et CC_PR_IS_FORK. Avec un composant compose, ils reçoivent également COMPOSE_PROJECT_NAME et COMPOSE_FILE, si bien que docker compose exec dans une tâche atteint le bon projet.
Rôles et répertoire de travail
Section intitulée « Rôles et répertoire de travail »Une définition lie des rôles aux dépôts de l’espace de travail, ce qui permet à une pile de couvrir plusieurs dépôts :
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: un espace peut démarrer l’environnement s’il contient au moins un rôle ancre. Si deux définitions correspondent, la personne qui démarre choisit.required: la pile ne peut pas fonctionner sans ce dépôt.whenMissing: ce qui se passe quand l’espace n’a pas le rôle.addToSpaceajoute le dépôt sur sa branche par défaut et s’applique par défaut aux rôlesrequired.useSourcetransmet votre copie enregistrée, à traiter en lecture seule.skiplaisse la variable non définie et s’applique par défaut dans les autres cas.- Démarrer exige un droit
writesur un dépôt ancre de l’espace et un accès en lecture à tous les autres dépôts liés.
Une commande s’exécute dans le premier rôle déclaré dans repos, jamais dans un autre rôle que possède l’espace par hasard : une définition à un seul dépôt n’a donc pas à le mentionner. Tout composant peut le remplacer avec "cwd": { "role": "e2e", "path": "packages/ui" }. Les deux champs sont facultatifs. Lorsque le premier rôle pourrait manquer dans un espace, parce qu’il n’est ni required ni le seul ancrage, chaque composant doit nommer son rôle.
Ports et URL
Section intitulée « Ports et URL »Control Center attribue les ports de l’hôte avant tout démarrage, depuis une plage commune à tout l’hôte (42000 à 49999 par défaut, par blocs de 32). Un port reste le même pendant toute la vie de l’environnement, et les ports compose se lient uniquement à 127.0.0.1.
- Les ports compose n’ont pas besoin d’être déclarés. Lisez-les avec
{port.postgres.5432}ouCC_ENV_PORT_POSTGRES_5432. - Les autres ports se déclarent là où ils servent, avec
"port": "web"ou"ports": ["web", "hmr"], et se lisent avec{port.web}. Un processus doté d’un port reçoit aussiPORTetHOST=127.0.0.1.
Les points de terminaison HTTP reçoivent une URL sur le routeur du serveur, qui écoute sur un seul port de bouclage :
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>est la branche sous forme de slug, oupr-<n>dans un espace de PR.<project>estnaming.project, sinon le nom de la définition.- Les noms
*.localhostpointent vers le bouclage : ils ne demandent ni entrée hosts ni DNS, et le nom d’hôte sépare les cookies entre environnements. - Les ports compose qui répondent en HTTP sont détectés, et
httpsur le composant remplace cette détection. Un processus a besoin de"endpoint": { "role": "web", "primary": true }, qui rend aussi{url.web}disponible. - Dans le navigateur (VM), utilisez Ouvrir dans Browser (VM).
https://web--fix-login--shop.localhost/y atteint la même route. - Le libellé complet reste sous 63 caractères : les noms longs sont raccourcis avec un hachage.
- Deux points de terminaison n’ont pas de domaine parent commun. Une application qui a besoin d’un même cookie sur les deux doit les servir depuis un seul point de terminaison.
Pour les URL à enregistrer à l’avance, comme les redirections OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } fournit un ensemble fixe de noms.
policy décide quand les environnements tournent. autoCreate vaut off, prSpaces ou allSpaces, idleStopMinutes vaut 240 par défaut, followPrHead synchronise un environnement de PR quand sa tête bouge, et maxRunning (6 par défaut) fait proposer par Démarrer l’arrêt de l’environnement utilisé le moins récemment.
Exemple : application compose
Section intitulée « Exemple : application compose »Une application web et Postgres dans un même fichier compose, avec un .env ignoré par git, des migrations et une tâche de test. seedFiles copie des fichiers nommés depuis votre copie enregistrée dans chaque nouvel arbre de travail.
{ "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 permet à un service sans contrôle de santé propre de bloquer le composant suivant. Sans cela, un conteneur en marche compte comme prêt, et les migrations peuvent devancer une base de données encore en démarrage.
Chaque démarrage et chaque actualisation lance up avec --remove-orphans, de sorte qu’un service retiré du fichier compose s’arrête et libère son port. Les images sont construites au démarrage et à l’actualisation, sauf si le composant définit "build": false.
Exemple : CLI personnalisée
Section intitulée « Exemple : CLI personnalisée »Un outil fictif acme qui gère ses conteneurs, ses domaines et son TLS. Control Center fournit {name} et apprend tout le reste de status. Il ne déduit jamais les noms d’hôte d’un outil et ne modifie jamais /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,statusetdestroysont obligatoires. Control Center choisitcreateoustartd’après le statut qu’il lit. Tout verbe peut être{ "shell": "…" }au lieu d’un argv.interactivedésigne les verbes, parmicreate,startetreset, qui peuvent demander ce dont ils ont besoin sur un terminal. Lorsqu’un de ces verbes se termine avec le code 3 pour une personne qui a appuyé sur Démarrer, Control Center relance le même verbe dans un onglet de terminal, et le démarrage se poursuit une fois qu’il se termine avec le code 0. Là, la conditioninteractiveest vraie etCC_ENV_INTERACTIVE=1est défini, de sorte que{ "if": "!interactive", "args": ["--json"] }conserve la sortie machine pour le canal non interactif. Un démarrage par un agent, ou un démarrage automatique, n’ouvre jamais de terminal : l’environnement affiche Action requise et attend.- Un
destroyqui échoue supprime tout de même l’environnement lorsquestatusannonce ensuitemissing, de sorte qu’un environnement que l’outil n’a plus peut toujours être supprimé. listpermet à Control Center de remarquer un environnement que l’outil a perdu. Il n’est marqué disparu que lorsque son nom est absent delistet questatusindique alorsmissing. Une sortie qui ne se lit pas comme une liste ne modifie rien.{service}danslogsetexecdoit être un seul mot qui ne commence pas par-, et l’un des services que l’outil a signalés en dernier lorsqu’il en a signalé.statusMaplit le JSON de l’outil avec des pointeurs JSON, où*correspond à chaque élément. Les règles d’état sont ordonnées et la première correspondance l’emporte. Une condition estpathavecequals, ouanyounoneavecwhere.keepsDataOnStop: falsedésactive l’arrêt sur inactivité et ajoute un avertissement de perte de données à Arrêter. Utilisez-le quand l’arrêt perd des données.routing.mode: "tool"relie les noms d’hôte de l’outil au navigateur (VM) et aux agents. Le domaine doit se terminer par.test,.localhostou.internal, et une URL signalée hors de ce domaine est ignorée.
Un outil dont vous êtes l’auteur peut se passer de statusMap et imprimer le contrat de statut décrit à la fin de cette page.
Exemple : monorepo pnpm
Section intitulée « Exemple : monorepo pnpm »Uniquement des processus et des tâches, sans conteneurs. L’application web trouve l’API grâce à {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"] } ]}- Chaque processus est un onglet de terminal que vous pouvez ouvrir, lire et dans lequel vous pouvez écrire, si vous avez un accès en écriture à chaque dépôt de l’espace (voir Qui peut enregistrer quoi). Fermer l’onglet ne l’arrête pas.
readyacceptehttp(une URL complète),tcp(host:port) oulogMatch(une expression régulière).restartvauton-failure(par défaut),alwaysounever.restartOnredémarre le processus quand un chemin modifié correspond.optionsdevient un formulaire sur Démarrer, etagentDefaults’applique aux exécutions lancées par un agent.
Exemple : application de bureau
Section intitulée « Exemple : application de bureau »Une application de bureau avec une étape de build. Une application fonctionne de la même façon quelle que soit sa technologie, car Control Center travaille au niveau des fenêtres du système et n’a besoin d’aucun hook ni SDK dans l’application.
{ "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" } ]}Une application ne démarre pas avec l’environnement. Quelqu’un clique sur Lancer, et prepare s’exécute d’abord. Recompiler et relancer relance cette paire. enabledWhen s’applique à l’application et à sa tâche prepare, et Lancer est refusé tant que l’un des deux est désactivé. Une application compte comme en marche tant qu’un processus de son groupe de processus tourne, de sorte qu’un lanceur qui démarre l’application puis se termine convient. Si tout a disparu dans les 5 secondes environ suivant Lancer, l’application s’affiche en échec avec ses dernières lignes de journal. Ensuite, une sortie propre s’affiche comme fermée et un plantage montre les dernières lignes de journal, sans que l’une ni l’autre ne la redémarre. Un redémarrage du serveur ferme l’application et ne la relance jamais, et l’arrêt sur inactivité laisse tranquille une application en marche.
Autorisations et limites des applications de bureau
Section intitulée « Autorisations et limites des applications de bureau »- Sur macOS, accordez une fois à Control Center Enregistrement de l’écran et Accessibilité dans Réglages Système. L’hôte du serveur a besoin d’une session graphique : un serveur sans interface refuse de lancer une application.
- Lancez directement le binaire.
open -aconfie l’application à LaunchServices et elle quitte l’arbre de processus suivi par Control Center, de sorte que l’application s’affiche en échec juste après son lancement. - Les fenêtres restent sur un écran. macOS ne capture pas une fenêtre placée hors de tout écran : une application utilisée par un agent est donc visible sur l’écran du serveur. Elle n’a pas besoin du focus.
"isolate": "home"donne à l’application un répertoire personnel privé viaHOME,XDG_*etCFFIXED_USER_HOME, pour que des copies de deux espaces tournent côte à côte.NSUserDefaultsn’est pas isolé : les préférences Cocoa etshared_preferencesde Flutter restent partagées entre les copies.isolatene s’applique qu’au processus lancé. Un lanceur de chaîne d’outils commeflutter runa besoin du vrai répertoire personnel : associez doncisolateà un binaire compilé. Si l’application a son propre réglage, comme--user-data-dir, préférez-le.- Les agents pilotent la fenêtre avec
app_use, qui ne peut atteindre que l’arbre de processus de cet environnement. Un agent voit la fenêtre, pas le bureau. Les lancements par un agent passent par la politique d’actions et demandent confirmation par défaut, et la saisie de l’agent s’arrête quand une personne a le contrôle. "input": "background"(par défaut) envoie les événements au processus."foreground"active la fenêtre et prend le contrôle du curseur.
Tâches d’arbre de travail
Section intitulée « Tâches d’arbre de travail »Les tâches provision et archive exécutent l’installation et le nettoyage du dépôt avec son arbre de travail. L’icône sur la ligne d’un dépôt dans Paramètres → Espace de travail → Dépôts ouvre la définition du dépôt.
Ces tâches suivent l’arbre de travail, pas l’environnement : elles s’exécutent donc dans les espaces où personne ne clique sur Démarrer :
provision |
archive |
|
|---|---|---|
| S’exécute | À la création de l’arbre de travail du rôle, dans n’importe quel espace | Juste avant la destruction de cet arbre de travail |
| En cas d’échec | Le provisionnement échoue et l’arbre de travail est détruit | Enregistré, ne bloque jamais la suppression |
| Délai par défaut | 5 minutes | 2 minutes |
| Voit | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
La même chose |
Un dépôt sans pile a seulement besoin d’une définition contenant ses tâches. Comme il n’y a rien à démarrer, aucun rôle ancre n’est nécessaire :
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Il n’y a pas encore d’environnement : ces tâches ne peuvent donc pas utiliser
{name},{port.*},{url.*},{opt.*}nienabledWhen, et elles ne reçoivent pas leenvde la définition. - Une seule définition peut contenir des tâches
provisionetarchivepour un dépôt. Les autres peuvent le lier pour tout le reste. "when": ["provision", "change"]réinstalle aussi quand un fichier de verrouillage change.- Une tâche s’exécute pour l’arbre de travail de son rôle
cwd: une définition multi-dépôts peut donc configurer chaque dépôt séparément. - Une exécution de test définit
CC_SCRIPT_TEST=1. Une nouvelle tentative repart d’un arbre de travail propre : écrivez des tâches qui supportent une réexécution.
Les agents n’obtiennent jamais le socket Docker. Dans un espace doté d’une définition éligible, une exécution reçoit cc-env dans son PATH. L’espace vient de l’exécution : un agent ne peut donc agir que sur son propre environnement, et chaque commande passe par la politique d’actions.
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>Avec un composant compose, un shim docker autorise aussi docker compose avec ps, logs, exec, port, restart et top, et seulement sur le projet compose propre à cet environnement. Aucune option ne peut précéder le verbe, et chaque verbe accepte une courte liste d’options : logs ne peut pas suivre le flux, et exec n’accepte que -T (ou --no-tty). Les options qui dirigent compose vers un autre fichier ou projet (-f, -p, --project-directory, --env-file, --profile) sont refusées, où qu’elles apparaissent. Tout le reste se termine avec le code 5 et « not available in Control Center agent runs ».
Un dépôt dont les skills appellent son propre outil peut continuer ainsi. Un bloc agentPassthrough sur un composant cli déclare les commandes que les agents peuvent exécuter. Seules les commandes déclarées par la définition approuvée passent, et chacune s’exécute sur l’hôte : elle porte donc la règle Exécuter des commandes sur l’hôte, qui demande d’abord confirmation par défaut :
"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 nomme l’opération dont la politique s’applique. positionalName force cet argument sur l’environnement de cet espace, nameFilter y filtre la sortie JSON, et chaque valeur de pathFlags doit se résoudre dans les arbres de travail de l’exécution. Une commande qui ne correspond à aucune règle se termine avec le code 5.
Les mêmes opérations existent sous forme d’outils : environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app et environment_stop_app. Les agents en bac à sable atteignent directement leurs ports et les noms d’hôte de leur environnement via le proxy de l’exécution : demandez-leur donc de lire les points de terminaison dans environment_status plutôt que de deviner une URL.
Pull requests de fork
Section intitulée « Pull requests de fork »Le code d’une PR de fork n’est pas fiable, et en placement sur l’hôte il s’exécute sous l’utilisateur système du serveur. policy.forkPrs décide de la suite :
| Valeur | Effet | Par défaut pour |
|---|---|---|
rig |
Le fichier compose s’exécute dans une VM, sans invite | Les définitions n’ayant que des composants compose et task |
approval |
Chaque démarrage exige un administrateur | Toutes les autres définitions |
deny |
Refusé | Aucune |
- Les
seedFilesne sont jamais copiés pour un fork, car ce sont généralement des secrets. Un fichier compose qui en monte un signale le fichier manquant par son nom. - Les tâches
provisionetarchivesont ignorées, sauf si la politique estrig: elles s’exécutent alors dans la VM. - En placement sur l’hôte,
privileged, les espaces de noms de l’hôte, un montage du socket Docker,deviceset les montages hors des arbres de travail de l’espace sont refusés sur un fork. Dans les espaces de confiance, ils ne déclenchent qu’un avertissement.
Placement en rig
Section intitulée « Placement en rig »"placement": "rig" exécute les composants compose et task dans une microVM dédiée. Les définitions avec des composants process, cli ou app ne sont pas éligibles. Le fichier compose s’exécute sans modification, sans socket Docker de l’hôte ni identifiants de l’opérateur, et l’accès réseau se limite aux registres dont ses images ont besoin. L’arbre de travail est monté en direct.
- Invités arm64. Les invités sont en arm64 sur Apple Silicon : les images uniquement amd64 ne fonctionnent pas.
- Les registres privés sont refusés. Les invités n’ont aucun identifiant de registre : une image sur un registre hors des registres publics connus est refusée avant le démarrage de la VM. Un dépôt privé sur un registre public échoue quand l’invité le récupère.
- 16 Gio de stockage. Toutes les images et tous les volumes de la pile partagent un disque de 16 Gio, qui ne peut pas être agrandi.
- Le premier démarrage est lent. Les couches d’image sont propres à chaque VM : le premier démarrage récupère tout. Un rig arrêté conserve son disque.
- Les images de base doivent être lisibles. Un Dockerfile qui nomme son image de base via une variable ne peut pas être planifié, car l’accès réseau est fixé au démarrage.
- Durée de vie.
policy.rigTtlHoursmet fin à la VM, après 24 heures par défaut.
Contrat de statut pour les auteurs d’outils
Section intitulée « Contrat de statut pour les auteurs d’outils »Un composant cli sans statusMap attend le contrat natif, cc-env/1. Le verbe status imprime cet objet sur 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": "…" }}statevautready,starting,stopped,failedoumissing.missingmène àcreate,stoppedetfailedmènent àstart. Signalezmissingavec le code de sortie 0 : unstatusen échec compte commefailed.- Seul
stateest nécessaire. Les champs inconnus sont ignorés, et une sortie illisible s’affiche comme dégradée, avec le texte brut en détail. - Une URL doit être en bouclage, en
*.localhostou sousrouting.domain, sinon elle est ignorée. needsRecreate: trueaffiche Recréer, qui supprime les données. Control Center n’agit jamais de lui-même sur cette valeur.- Le verbe
listimprime un tableau JSON de noms, ou d’objets avec unname.
Les codes de sortie valent pour tous les verbes :
| Code | Signification |
|---|---|
| 0 | OK |
| 3 | Une réponse est attendue dans un terminal, par exemple un mot de passe sudo. Un verbe listé dans interactive s’exécute à nouveau dans un onglet de terminal pour la personne qui a appuyé sur Démarrer. Sinon, Exécuter dans le terminal ouvre un terminal d’espace avec la command de l’outil saisie mais non exécutée, puis Réessayer relance l’opération. Control Center n’exécute jamais sudo et ne répond jamais à une invite |
| 4 | Connexion requise. La command de l’outil indique comment |
| 5 | Quelque chose dont il dépend n’est pas disponible, comme un moteur de conteneurs qui ne tourne pas |
| Autre | Échec |
Les codes 3, 4 et 5 ne sont pas des échecs. L’environnement affiche Action requise et attend, et le démarrage suivant reprend là où celui-ci s’est arrêté. Une tâche qui se termine avec l’un d’eux signifie la même chose.
La progression va sur stderr, en JSON délimité par des sauts de ligne :
{"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"}Lorsqu’un environnement démarre, le panneau liste les composants par lesquels passe le démarrage, chacun avec un spinner, une coche ou une croix. Une ligne step indique ce que fait l’outil à cet instant, et son label s’affiche sous la ligne propre à l’outil ; les étapes n’ajoutent jamais de lignes. Le state d’une étape est pending, running, done ou failed, et une étape sans state est en cours. Une étape qui s’annonce à nouveau sous le même id (une chaîne ou un nombre, ou le même label à défaut) remplace ce qu’elle disait auparavant, de sorte qu’un outil avec un seul spinner peut garder un même id et changer le label. Sans ids, les étapes se suivent : une nouvelle termine la précédente. Quand la commande se termine, une étape encore en cours se termine comme la commande.
Une ligne log transporte une ligne de sortie que l’outil a enveloppée en JSON et se lit comme une sortie ordinaire. Une ligne note va dans la sortie de l’exécution, et une ligne avec "level": "warn" reste aussi sur l’environnement comme avertissement. Une dernière ligne de type error devient une erreur structurée, avec command proposée à la copie, et les 12 dernières lignes de sortie s’affichent sous son message. Sinon, Control Center affiche les 20 dernières lignes de stderr. Tout ce qui n’est pas du JSON est du journal ordinaire.