Configurar ambientes
Um ambiente é a stack em execução de um espaço: os serviços de que um branch precisa, isolados de todos os outros espaços, visíveis na barra lateral e acessíveis aos agentes. Pull requests também têm um, porque uma PR já tem seu próprio espaço.
Um administrador do espaço de trabalho escreve uma definição uma única vez. Depois, os membros clicam em Iniciar na seção Ambiente da barra lateral de um espaço ou de uma PR. As definições ficam no banco de dados do espaço de trabalho, então um branch de funcionalidade nunca muda o que o Control Center executa, embora as ferramentas ainda executem o código desse branch.
Criar uma definição
Seção intitulada “Criar uma definição”- Abra Configurações → Espaço de trabalho → Ambientes. Só administradores do espaço de trabalho podem alterar definições, e só o proprietário do servidor pode salvar uma que roda no host do servidor (veja Quem pode salvar o quê).
- Clique em Nova definição e depois em Definição em branco ou Criar rascunho do repo. Um rascunho procura no repo arquivos compose, um
Procfilee scripts depackage.json, e a revisão do resultado fica com você. - Preencha o formulário ou use a aba JSON. Os exemplos desta página são esse JSON.
- Clique em Executar teste. Isso inicia um ambiente descartável, espera até ele ficar pronto e o destrói.
Salvar verifica uma definição de forma estrita. Um campo desconhecido, um valor do tipo errado ou uma opção escrita de forma errada é recusado, com seu caminho e o nome válido mais próximo, como repos.app.requird: Unknown field. Did you mean "required"?. Um $schema no nível superior é permitido.
Para manter uma definição em um repo, use Vincular um arquivo do repo. O Control Center lê o arquivo apenas do branch padrão e executa apenas a versão que foi aprovada: por um administrador do espaço de trabalho, ou pelo proprietário do servidor quando a definição roda no host. Uma versão mais nova mostra Atualização disponível e não muda nada até ser aprovada.
Quem pode salvar o quê
Seção intitulada “Quem pode salvar o quê”Uma definição de ambiente pode executar comandos no host do servidor como o próprio usuário do servidor. Essa decisão é do proprietário do servidor, não de um papel do espaço de trabalho:
- Uma definição roda no host quando tem colocação no host, uma verificação que executa um comando, ou uma tarefa
provisionouarchive. Essas tarefas rodam na worktree do espaço no host, independentemente da colocação. - Somente o proprietário do servidor pode salvar ou aprovar uma definição que roda no host. Isso inclui aprovar uma nova versão de um arquivo de repo vinculado. Um administrador do espaço de trabalho que tente recebe “Somente o proprietário do servidor pode salvar ou aprovar um ambiente que roda no host do servidor. Um administrador do espaço de trabalho pode usar um que roda em um rig.”
- Um administrador do espaço de trabalho pode salvar e aprovar uma definição que roda inteiramente em um rig:
"placement": "rig", sem comando de verificação e sem tarefaprovisionouarchive. - Membros iniciam, param e usam ambientes de qualquer forma.
- Uma definição que roda no host só executa depois que o proprietário atual do servidor a salvou ou aprovou. O próprio servidor registra essa aprovação e a verifica antes de cada início, verificação, tarefa e sincronização da head de uma pull request. Uma definição que o proprietário atual não aprovou, como uma que um proprietário anterior salvou, fica aguardando sob a sua linha na lista de ambientes e no editor. O proprietário do servidor vê “Roda neste servidor. Aprove para permitir que ele inicie.” com Aprovar, que salva a definição sem alterações; todos os outros veem “Roda neste servidor. O proprietário do servidor precisa aprová-lo antes que ele possa iniciar.”
- Um ambiente retido para essa aprovação diz “O proprietário do servidor ainda não aprovou este ambiente, então ele não pode rodar neste servidor.” O proprietário do servidor vê, em vez disso, “Você ainda não aprovou este ambiente. Ele roda neste servidor, então inicia assim que você aprovar a definição.” com Revisar e aprovar, que abre a definição.
- Os terminais de processos de um ambiente, e o terminal que um início abre quando precisa de você, rodam no host do servidor. Digitar neles, redimensioná-los ou fechá-los exige acesso de escrita a todos os repositórios que o espaço expõe, legíveis pelo seu próprio login na forja: o mesmo que iniciar o ambiente. Qualquer outra pessoa não consegue alcançar esses terminais.
A menor definição
Seção intitulada “A menor definição”Um repo compose simples precisa só disto:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Todo o resto tem um valor padrão: o arquivo compose é descoberto, todos os serviços são executados, as portas são atribuídas, os endpoints HTTP são detectados e o ambiente recebe o nome do branch.
Tipos de componente
Seção intitulada “Tipos de componente”Um ambiente é uma lista ordenada de componentes. Cada um espera o anterior ficar pronto, a menos que after indique outros, e a parada acontece na ordem inversa. enabledWhen condiciona um componente a uma opção ou a um papel, por exemplo opt.seed, !opt.seed ou repo.web. Um componente cujo papel é opcional e não está no espaço fica de fora da mesma forma, sem precisar de enabledWhen: ele não inicia e não tem {port.*} nem {url.*}, então outro componente que os leia faz o início falhar.
| Tipo | Quem executa | Para que serve |
|---|---|---|
compose |
O driver compose do Control Center | Qualquer arquivo compose, um por ambiente |
cli |
Sua ferramenta. O Control Center chama verbos mapeados e lê JSON | Uma ferramenta dona do próprio ciclo de vida, domínios e dados |
process |
O Control Center, em uma sessão de terminal supervisionada | Servidores de desenvolvimento e workers |
task |
O Control Center, uma vez por gatilho | Instalações, migrações, testes |
app |
O Control Center, quando alguém clica em Abrir app | Um aplicativo de desktop |
Componentes task recebem uma lista when:
| Gatilho | Quando executa |
|---|---|
provision |
Quando o worktree é criado (veja as tarefas de worktree mais abaixo) |
create |
Uma vez por ambiente, e de novo após uma redefinição |
start |
Em cada início |
change |
Após uma sincronização, quando um caminho alterado corresponde a onChange |
manual |
Sob demanda: Executar, cc-env run <id> ou environment_run_task |
archive |
Logo antes de o worktree ser destruído |
Uma tarefa sem nada a fazer em um início mostra Inativo e fica fora da lista de etapas exibida enquanto o ambiente inicia: uma tarefa manual ou change, ou uma tarefa create que já foi executada.
Um comando dado como array é argv, então os valores de opção nunca passam por um shell. Uma string, ou script com um array de linhas, é executada com bash -lc. Marcadores como {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} e {url.<role>} só são expandidos em argv. Comandos de shell leem os mesmos valores como variáveis CC_ENV_*, por exemplo $CC_ENV_PORT_WEB. Um marcador desconhecido em um componente que participa interrompe o início antes que qualquer coisa seja executada.
Cada comando e terminal de espaço também recebe CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> e, em espaços de PR, CC_PR_NUMBER e CC_PR_IS_FORK. Com um componente compose, recebem ainda COMPOSE_PROJECT_NAME e COMPOSE_FILE, de modo que docker compose exec em uma tarefa alcança o projeto certo.
Papéis e diretório de trabalho
Seção intitulada “Papéis e diretório de trabalho”Uma definição vincula papéis a repos do espaço de trabalho, para que uma stack possa abranger vários repos:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: um espaço pode iniciar o ambiente quando contém pelo menos um papel âncora. Se duas definições corresponderem, quem inicia escolhe.required: a stack não funciona sem este repo.whenMissing: o que acontece quando falta o papel ao espaço.addToSpaceadiciona o repo no branch padrão e é o valor padrão para papéisrequired.useSourcepassa sua cópia registrada, a ser tratada como somente leitura.skipdeixa a variável sem valor e é o padrão nos outros casos.- Para iniciar é preciso uma permissão
writeem um repo âncora do espaço e acesso de leitura a todos os outros repos vinculados.
Um comando é executado no primeiro papel declarado em repos, nunca em outro papel que o espaço tenha, então uma definição de um só repo nunca precisa mencionar isso. Qualquer componente pode mudar esse comportamento com "cwd": { "role": "e2e", "path": "packages/ui" }. Os dois campos são opcionais. Quando o primeiro papel poderia faltar em um espaço, por não ser required nem a única âncora, cada componente precisa informar o seu papel.
Portas e URLs
Seção intitulada “Portas e URLs”O Control Center atribui portas do host antes de qualquer início, a partir de um intervalo único para todo o host (42000 a 49999 por padrão, em blocos de 32). Uma porta permanece a mesma durante toda a vida do ambiente, e as portas compose se vinculam apenas a 127.0.0.1.
- Portas compose não precisam de declaração. Leia-as como
{port.postgres.5432}ouCC_ENV_PORT_POSTGRES_5432. - As outras portas são declaradas onde são usadas, com
"port": "web"ou"ports": ["web", "hmr"], e lidas como{port.web}. Um processo com porta também recebePORTeHOST=127.0.0.1.
Endpoints HTTP recebem uma URL no roteador do servidor, que escuta em uma única porta de loopback:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>é o branch como slug, oupr-<n>em um espaço de PR.<project>énaming.projectou, na falta dele, o nome da definição.- Nomes
*.localhostresolvem para loopback, então não precisam de entradas de hosts nem de DNS, e o nome de host mantém os cookies separados entre ambientes. - Portas compose que respondem HTTP são detectadas, e
httpno componente substitui essa detecção. Um processo precisa de"endpoint": { "role": "web", "primary": true }, que também disponibiliza{url.web}. - No navegador (VM), use Abrir no Browser (VM).
https://web--fix-login--shop.localhost/alcança a mesma rota ali. - O rótulo inteiro fica dentro de 63 caracteres, então nomes longos são encurtados com um hash.
- Dois endpoints não têm domínio pai comum. Um aplicativo que precise de um cookie nos dois tem de servi-los a partir de um só endpoint.
Para URLs que precisam ser registradas com antecedência, como redirecionamentos OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } fornece um conjunto fixo de nomes.
policy decide quando os ambientes rodam. autoCreate é off, prSpaces ou allSpaces, idleStopMinutes vale 240 por padrão, followPrHead sincroniza um ambiente de PR quando o head se move e maxRunning (padrão 6) faz Iniciar oferecer a parada do ambiente usado há mais tempo.
Exemplo: aplicativo compose
Seção intitulada “Exemplo: aplicativo compose”Um aplicativo web e Postgres em um arquivo compose, com um .env ignorado pelo git, migrações e uma tarefa de teste. seedFiles copia arquivos nomeados da sua cópia registrada para cada novo 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" } ]}healthchecks permite que um serviço sem verificação de saúde própria segure o próximo componente. Sem isso, um contêiner em execução conta como pronto, e as migrações podem correr à frente de um banco de dados que ainda está iniciando.
Todo início e toda atualização executam up com --remove-orphans, então um serviço removido do arquivo compose para e libera sua porta. As imagens são construídas no início e na atualização, a menos que o componente defina "build": false.
Exemplo: CLI própria
Seção intitulada “Exemplo: CLI própria”Uma ferramenta fictícia acme, dona dos próprios contêineres, domínios e TLS. O Control Center fornece {name} e descobre todo o resto por status. Ele nunca deduz os nomes de host de uma ferramenta e nunca edita /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,statusedestroysão obrigatórios. O Control Center escolhecreateoustartpelo status que lê. Qualquer verbo pode ser{ "shell": "…" }em vez de argv.interactivenomeia os verbos, entrecreate,startereset, que podem pedir o que precisam em um terminal. Quando um desses verbos termina com código 3 para uma pessoa que pressionou Iniciar, o Control Center executa o mesmo verbo de novo em uma aba de terminal, e o início segue quando ele termina com código 0. Ali a condiçãointeractiveé verdadeira eCC_ENV_INTERACTIVE=1está definido, então{ "if": "!interactive", "args": ["--json"] }mantém a saída de máquina para o pipe. Um início feito por um agente, ou um automático, nunca abre um terminal: o ambiente mostra Ação necessária e aguarda.- Um
destroyque falha ainda remove o ambiente quandostatusdepois informamissing, então um ambiente que a ferramenta não tem mais sempre pode ser removido. listpermite que o Control Center perceba um ambiente que a ferramenta perdeu. Ele só é marcado como sumido quando seu nome não aparece emlistestatusentão informamissing. Uma saída que não pode ser lida como lista não altera nada.{service}emlogseexecdeve ser uma única palavra que não começa com-, e um dos serviços que a ferramenta informou por último, quando informou algum.statusMaplê o JSON da própria ferramenta com ponteiros JSON, em que*corresponde a cada item. As regras de estado são ordenadas e a primeira correspondência vence. Uma condição épathcomequals, ouanyounonecomwhere.keepsDataOnStop: falsedesativa a parada por inatividade e acrescenta um aviso de perda de dados a Parar. Use quando parar perde dados.routing.mode: "tool"liga os nomes de host da ferramenta ao navegador (VM) e aos agentes. O domínio deve terminar em.test,.localhostou.internal, e uma URL informada fora dele é descartada.
Uma ferramenta própria pode dispensar statusMap e imprimir o contrato de status descrito no fim desta página.
Exemplo: monorepo pnpm
Seção intitulada “Exemplo: monorepo pnpm”Só processos e tarefas, sem contêineres. O aplicativo web encontra a API por meio de {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"] } ]}- Cada processo é uma aba de terminal que pode ser aberta, lida e usada para digitar, se você tiver acesso de escrita a todos os repositórios do espaço (veja Quem pode salvar o quê). Fechar a aba não o interrompe.
readyaceitahttp(uma URL completa),tcp(host:port) oulogMatch(uma expressão regular).restartéon-failure(o padrão),alwaysounever.restartOnreinicia o processo quando um caminho alterado corresponde.optionsvira um formulário em Iniciar, eagentDefaultvale para execuções iniciadas por um agente.
Exemplo: aplicativo de desktop
Seção intitulada “Exemplo: aplicativo de desktop”Um aplicativo de desktop com uma etapa de build. Um aplicativo funciona igual seja qual for a tecnologia, porque o Control Center trabalha no nível das janelas do sistema operacional e não precisa de hook nem SDK no aplicativo.
{ "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" } ]}Um aplicativo não inicia com o ambiente. Alguém clica em Abrir app, e prepare é executado primeiro. Recompilar e reabrir executa esse par de novo. enabledWhen se aplica ao aplicativo e à sua tarefa prepare, e Abrir app é recusado enquanto qualquer um dos dois estiver desligado. Um aplicativo conta como em execução enquanto algum processo do seu grupo de processos estiver rodando, então um lançador que inicia o aplicativo e termina está tudo bem. Se tudo sumir em cerca de 5 segundos após Abrir app, o aplicativo aparece como falho com suas últimas linhas de log. Depois disso, uma saída limpa aparece como fechada e uma falha mostra as últimas linhas de log, e nenhuma das duas o reinicia. Um reinício do servidor fecha o aplicativo e nunca o reabre, e a parada por inatividade deixa em paz um aplicativo em execução.
Permissões e limites de aplicativos de desktop
Seção intitulada “Permissões e limites de aplicativos de desktop”- No macOS, conceda uma vez ao Control Center Gravação de Tela e Acessibilidade nos Ajustes do Sistema. O host do servidor precisa de uma sessão gráfica: um servidor headless se recusa a abrir um aplicativo.
- Abra o binário diretamente.
open -aentrega o aplicativo ao LaunchServices e ele sai da árvore de processos que o Control Center acompanha, então o aplicativo aparece como falho logo após o lançamento. - As janelas ficam em um monitor. O macOS não captura uma janela fora de todos os monitores, então um aplicativo usado por um agente fica visível na tela do servidor. Ele não precisa de foco.
"isolate": "home"dá ao aplicativo uma pasta pessoal privada por meio deHOME,XDG_*eCFFIXED_USER_HOME, para que cópias de dois espaços rodem lado a lado.NSUserDefaultsnão é isolado, então as preferências Cocoa e oshared_preferencesdo Flutter continuam compartilhados entre as cópias.isolatevale apenas para o processo iniciado. Um lançador de toolchain comoflutter runprecisa da pasta pessoal real, então combineisolatecom um binário compilado. Se o aplicativo tiver uma configuração própria, como--user-data-dir, prefira essa.- Os agentes controlam a janela com
app_use, que só alcança a árvore de processos deste ambiente. Um agente vê a janela, não a área de trabalho. Aberturas feitas por agentes passam pela política de ações e perguntam por padrão, e a entrada do agente para enquanto uma pessoa tem o controle. "input": "background"(o padrão) envia eventos ao processo."foreground"ativa a janela e assume o cursor.
Tarefas de worktree
Seção intitulada “Tarefas de worktree”As tarefas provision e archive executam a configuração e a limpeza de um repo junto com o worktree dele. O ícone na linha de um repo em Configurações → Espaço de trabalho → Repositórios abre a definição do repo.
Essas tarefas seguem o worktree, não o ambiente, então rodam em espaços onde ninguém clica em Iniciar:
provision |
archive |
|
|---|---|---|
| Executa | Quando o worktree do papel é criado, em qualquer espaço | Logo antes de esse worktree ser destruído |
| Em caso de falha | O provisionamento falha e o worktree é destruído | Registrado, nunca bloqueia a exclusão |
| Tempo limite padrão | 5 minutos | 2 minutos |
| Vê | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
O mesmo |
Um repo sem stack precisa apenas de uma definição com as suas tarefas. Como não há nada para iniciar, nenhum papel âncora é necessário:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Ainda não existe ambiente, então essas tarefas não podem usar
{name},{port.*},{url.*},{opt.*}nemenabledWhen, e não recebem oenvda definição. - Só uma definição pode ter tarefas
provisionearchivepara um repo. As outras ainda podem vinculá-lo para todo o resto. "when": ["provision", "change"]também reinstala quando um lockfile muda.- Uma tarefa roda para o worktree do seu papel
cwd, então uma definição com vários repos pode configurar cada repo separadamente. - Uma execução de teste define
CC_SCRIPT_TEST=1. Uma nova tentativa parte de um worktree limpo, então escreva tarefas que aguentem ser executadas de novo.
Agentes
Seção intitulada “Agentes”Os agentes nunca recebem o socket do Docker. Em um espaço com uma definição elegível, uma execução recebe cc-env no seu PATH. O espaço vem da execução, então um agente só pode agir no próprio ambiente, e cada comando passa pela política de ações.
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>Com um componente compose, um shim docker também permite docker compose com ps, logs, exec, port, restart e top, e somente contra o projeto compose próprio deste ambiente. Nenhuma flag pode vir antes do verbo, e cada verbo aceita uma lista curta de opções: logs não pode acompanhar a saída e exec aceita apenas -T (ou --no-tty). Opções que apontam o compose para outro arquivo ou projeto (-f, -p, --project-directory, --env-file, --profile) são recusadas onde quer que apareçam. Todo o resto sai com código 5 e “not available in Control Center agent runs”.
Um repo cujas skills chamam a própria ferramenta pode continuar assim. Um bloco agentPassthrough em um componente cli declara quais comandos os agentes podem executar. Somente os comandos que a definição aprovada declara passam adiante, e cada um roda no host, então ele carrega a regra Executar comandos no host, que pergunta antes por padrão:
"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 indica a operação cuja política se aplica. positionalName força esse argumento para o ambiente deste espaço, nameFilter filtra a saída JSON para ele e todo valor de pathFlags precisa resolver dentro dos worktrees da execução. Um comando que não corresponde a nenhuma regra sai com código 5.
As mesmas operações existem como ferramentas: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app e environment_stop_app. Agentes em sandbox alcançam diretamente suas portas e os nomes de host do seu ambiente pelo proxy da execução, então instrua-os a ler os endpoints em environment_status em vez de adivinhar uma URL.
Pull requests de fork
Seção intitulada “Pull requests de fork”O código de uma PR de fork não é confiável e, na colocação no host, roda como o usuário do sistema do servidor. policy.forkPrs decide o que acontece:
| Valor | Efeito | Padrão para |
|---|---|---|
rig |
O arquivo compose roda em uma VM, sem perguntar | Definições só com componentes compose e task |
approval |
Cada início precisa de um administrador | Todas as outras definições |
deny |
Recusado | Nenhuma |
seedFilesnunca são copiados para um fork, porque costumam ser segredos. Um arquivo compose que monte um deles informa o arquivo ausente pelo nome.- Tarefas
provisionearchivesão ignoradas, a menos que a política sejarig, caso em que rodam na VM. - Na colocação no host,
privileged, namespaces do host, um bind do socket do Docker,devicese binds fora dos worktrees do espaço são recusados em um fork. Em espaços confiáveis, geram apenas um aviso.
Colocação em rig
Seção intitulada “Colocação em rig”"placement": "rig" executa componentes compose e task em uma microVM dedicada. Definições com componentes process, cli ou app não são elegíveis. O arquivo compose roda sem alterações, sem socket do Docker do host e sem credenciais do operador, e o acesso à rede fica limitado aos registros de que suas imagens precisam. O worktree é montado ao vivo.
- Convidados arm64. Os convidados são arm64 no Apple Silicon, então imagens somente amd64 não rodam.
- Registros privados são recusados. Os convidados não têm credenciais de registro, então uma imagem em um registro fora dos públicos conhecidos é recusada antes de a VM iniciar. Um repositório privado em um registro público falha quando o convidado o baixa.
- 16 GiB de armazenamento. Todas as imagens e volumes da stack compartilham um disco de 16 GiB, que não pode ser aumentado.
- A primeira inicialização é lenta. As camadas de imagem são por VM, então a primeira inicialização baixa tudo. Um rig parado mantém o disco.
- As imagens base precisam ser legíveis. Um Dockerfile que indica a imagem base por uma variável não pode ser planejado, porque o acesso à rede é fixado na inicialização.
- Duração.
policy.rigTtlHoursencerra a VM, após 24 horas por padrão.
Contrato de status para autores de ferramentas
Seção intitulada “Contrato de status para autores de ferramentas”Um componente cli sem statusMap espera o contrato nativo, cc-env/1. O verbo status imprime este objeto em 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": "…" }}stateéready,starting,stopped,failedoumissing.missingleva acreate, estoppedefailedlevam astart. Informemissingcom código de saída 0: umstatuscom falha conta comofailed.- Só
stateé necessário. Campos desconhecidos são ignorados, e uma saída que não pode ser interpretada aparece como degradada, com o texto bruto como detalhe. - Uma URL precisa ser de loopback,
*.localhostou estar sobrouting.domain; caso contrário, é descartada. needsRecreate: truemostra Recriar, que descarta dados. O Control Center nunca age sozinho com base nisso.- O verbo
listimprime um array JSON de nomes, ou de objetos com umname.
Os códigos de saída valem para todos os verbos:
| Código | Significado |
|---|---|
| 0 | OK |
| 3 | É preciso uma resposta em um terminal, como uma senha do sudo. Um verbo listado em interactive roda de novo em uma aba de terminal para a pessoa que pressionou Iniciar. Caso contrário, Executar no terminal abre um terminal de espaço com o command da ferramenta digitado, mas não executado, e depois Tentar novamente tenta de novo. O Control Center nunca executa sudo nem responde a um prompt |
| 4 | Login necessário. O command da ferramenta indica como |
| 5 | Algo do que ele depende não está disponível, como um runtime de contêineres que não está rodando |
| Outro | Falha |
Os códigos 3, 4 e 5 não são falhas. O ambiente mostra Ação necessária e aguarda, e o próximo início retoma de onde aquele parou. Uma tarefa que termina com um deles significa o mesmo.
O progresso vai para stderr como JSON delimitado por quebras de linha:
{"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"}Enquanto um ambiente inicia, o painel lista os componentes pelos quais o início passa, cada um com um spinner, um check ou uma cruz. Uma linha step diz o que a ferramenta está fazendo agora, e o seu label aparece abaixo da linha da própria ferramenta; etapas nunca adicionam linhas. O state de uma etapa é pending, running, done ou failed, e uma etapa sem state está em execução. Uma etapa que informa de novo com o mesmo id (um texto ou um número, ou o mesmo label se não houver um) substitui o que dizia antes, então uma ferramenta com um único spinner pode manter um só id e mudar o label. Sem ids, as etapas se sucedem: uma nova encerra a anterior. Quando o comando termina, uma etapa ainda em execução termina do mesmo jeito que o comando.
Uma linha log traz uma linha de saída que a ferramenta embrulhou em JSON e é lida como saída comum. Uma linha note vai para a saída da execução, e uma com "level": "warn" também fica no ambiente como aviso. Uma última linha do tipo error vira um erro estruturado, com command oferecido para cópia, e as últimas 12 linhas de saída aparecem abaixo de seu message. Sem ela, o Control Center mostra as últimas 20 linhas de stderr. Tudo o que não é JSON é saída de log comum.