Scripts de repo

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

Há dois tipos:

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

Onde os scripts são executados

Os dois scripts são executados via bash -lc (um shell de login, então ferramentas instaladas via Homebrew/nvm estão no PATH) com o worktree como diretório de trabalho, e com estas variáveis de ambiente definidas:

Variável	Valor
CC_WORKSPACE_PATH	O worktree (o cwd do script)
CC_ROOT_PATH	O repo de origem registrado — o seu próprio checkout
CC_SPACE_ID	O espaço ao qual o worktree pertence
CC_SPACE_NAME	O nome de exibição do espaço
CC_REPO_NAME	O nome de exibição do repo

Por exemplo, um script de configuração que instala 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 código de saída diferente de zero (ou excede o tempo limite de 5 minutos) faz o provisionamento do espaço falhar: o espaço mostra o estado de falha com uma opção de tentar novamente, e o final da saída da execução é registrado. Uma nova tentativa provisiona a partir de um worktree limpo e executa o script de novo — escreva os scripts de configuração de modo que uma nova execução depois de uma instalação parcial funcione (os gerenciadores de pacotes já se comportam assim).
• Um script de arquivamento é de melhor esforço: uma falha (ou o tempo limite de 2 minutos) é registrada, mas nunca bloqueia a exclusão. O arquivamento roda em caminhos de GC onde não há ninguém para responder a um prompt (espaço excluído, PR mesclada, limpeza agendada).

A configuração só é executada em um worktree novo: redespachar agentes para um espaço já aquecido reutiliza o checkout existente e não paga a instalação de novo.

Histórico de execuções

Toda execução é registrada com seu status, duração, código de saída e um trecho final limitado da saída, visível na mesma caixa de diálogo de configurações em “Execuções recentes” (a assinatura repos.watchScriptRuns a transmite ao vivo).

Permissões

Os scripts são shell que o servidor executa, então escrevê-los é restrito a administradores do espaço de trabalho e protegido pela classe de ação processSpawn — a mesma rede de guardrails que barra todas as outras operações de spawn de processos.