Scripts de repo

Os scripts de repo são scripts shell que configura por repositório (Definições → Repositórios → o ícone de terminal na linha de um repo) e que o servidor do Control Center executa contra a worktree de um espaço desse repo — o checkout isolado em <dataDir>/<workspaceId>/spaces/<spaceId>/repos/<repo>/, onde os agentes trabalham.

Existem dois tipos:

Script	Quando é executado	Para que serve
Configuração	Logo após o aprovisionamento de uma worktree para um espaço	Instalar dependências, gerar ficheiros, copiar .env
Arquivamento	Pouco antes de uma worktree ser destruída ou recolhida pelo GC	Limpar recursos fora da worktree (redes do Docker, túneis, estado externo)

Onde são executados os scripts

Ambos os scripts são executados através de bash -lc (um shell de início de sessão, para que as ferramentas instaladas com Homebrew/nvm fiquem no PATH), com a worktree como diretório de trabalho, e com estas variáveis de ambiente definidas:

Variável	Valor
CC_WORKSPACE_PATH	A worktree (o diretório de trabalho do script)
CC_ROOT_PATH	O repo de origem registado — o seu próprio checkout
CC_SPACE_ID	O espaço a que a worktree pertence
CC_SPACE_NAME	O nome a apresentar do espaço
CC_REPO_NAME	O nome a apresentar do repo

Por exemplo, um script de configuração que instala as dependências e traz o .env ignorado pelo Git do repo:

pnpm install
cp "$CC_ROOT_PATH/.env" .env
pnpm run build

Comportamento em caso de falha

• Um script de configuração que termina com um código de saída diferente de zero (ou que excede o seu tempo limite de 5 minutos) faz falhar o aprovisionamento do espaço: o espaço mostra o estado de falha com uma opção de repetir, e a cauda da saída da execução é registada. Uma nova tentativa aprovisiona a partir de uma worktree limpa e volta a executar o script — escreva os scripts de configuração de modo a que uma nova execução após uma instalação parcial funcione (os gestores de pacotes já se comportam assim).
• Um script de arquivamento é executado ao melhor esforço: uma falha (ou o seu tempo limite de 2 minutos) é registada, mas nunca bloqueia a eliminação. O arquivamento é executado em caminhos de GC onde não há ninguém para responder a um pedido (espaço eliminado, PR com merge, limpeza agendada).

A configuração só é executada numa worktree nova: voltar a despachar agentes para um espaço quente reutiliza o checkout existente e não volta a pagar a instalação.

Histórico de execuções

Cada execução é registada com o seu estado, a sua duração, o seu código de saída e uma cauda de saída limitada, visível na mesma caixa de diálogo de definições em «Execuções recentes» (a subscrição repos.watchScriptRuns transmite-a em direto).

Permissões

Como os scripts são shell que o servidor executa, escrevê-los está reservado aos administradores do espaço de trabalho e é protegido pela classe de ações processSpawn — a mesma rede de guardrails que controla qualquer outra operação de lançamento de processos.