Pular para o conteúdo

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.

  1. 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ê).
  2. 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 Procfile e scripts de package.json, e a revisão do resultado fica com você.
  3. Preencha o formulário ou use a aba JSON. Os exemplos desta página são esse JSON.
  4. 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.

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 provision ou archive. 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 tarefa provision ou archive.
  • 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.

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.

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.

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. addToSpace adiciona o repo no branch padrão e é o valor padrão para papéis required. useSource passa sua cópia registrada, a ser tratada como somente leitura. skip deixa a variável sem valor e é o padrão nos outros casos.
  • Para iniciar é preciso uma permissão write em 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.

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} ou CC_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 recebe PORT e HOST=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, ou pr-<n> em um espaço de PR. <project> é naming.project ou, na falta dele, o nome da definição.
  • Nomes *.localhost resolvem 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 http no 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.

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.

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, status e destroy são obrigatórios. O Control Center escolhe create ou start pelo status que lê. Qualquer verbo pode ser { "shell": "…" } em vez de argv.
  • interactive nomeia os verbos, entre create, start e reset, 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ção interactive é verdadeira e CC_ENV_INTERACTIVE=1 está 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 destroy que falha ainda remove o ambiente quando status depois informa missing, então um ambiente que a ferramenta não tem mais sempre pode ser removido.
  • list permite que o Control Center perceba um ambiente que a ferramenta perdeu. Ele só é marcado como sumido quando seu nome não aparece em list e status então informa missing. Uma saída que não pode ser lida como lista não altera nada.
  • {service} em logs e exec deve ser uma única palavra que não começa com -, e um dos serviços que a ferramenta informou por último, quando informou algum.
  • statusMap lê 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 é path com equals, ou any ou none com where.
  • keepsDataOnStop: false desativa 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, .localhost ou .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.

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.
  • ready aceita http (uma URL completa), tcp (host:port) ou logMatch (uma expressão regular). restart é on-failure (o padrão), always ou never. restartOn reinicia o processo quando um caminho alterado corresponde.
  • options vira um formulário em Iniciar, e agentDefault vale para execuções iniciadas por um agente.

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.

  • 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 -a entrega 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 de HOME, XDG_* e CFFIXED_USER_HOME, para que cópias de dois espaços rodem lado a lado. NSUserDefaults não é isolado, então as preferências Cocoa e o shared_preferences do Flutter continuam compartilhados entre as cópias.
  • isolate vale apenas para o processo iniciado. Um lançador de toolchain como flutter run precisa da pasta pessoal real, então combine isolate com 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.

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.*} nem enabledWhen, e não recebem o env da definição.
  • Só uma definição pode ter tarefas provision e archive para 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.

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.

Janela do terminal
cc-env status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-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.

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
  • seedFiles nunca são copiados para um fork, porque costumam ser segredos. Um arquivo compose que monte um deles informa o arquivo ausente pelo nome.
  • Tarefas provision e archive são ignoradas, a menos que a política seja rig, caso em que rodam na VM.
  • Na colocação no host, privileged, namespaces do host, um bind do socket do Docker, devices e binds fora dos worktrees do espaço são recusados em um fork. Em espaços confiáveis, geram apenas um aviso.

"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.rigTtlHours encerra a VM, após 24 horas por padrão.

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, failed ou missing. missing leva a create, e stopped e failed levam a start. Informe missing com código de saída 0: um status com falha conta como failed.
  • 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, *.localhost ou estar sob routing.domain; caso contrário, é descartada.
  • needsRecreate: true mostra Recriar, que descarta dados. O Control Center nunca age sozinho com base nisso.
  • O verbo list imprime um array JSON de nomes, ou de objetos com um name.

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.