Cloud Agent Builds
Os Builds preparam seu ambiente do Cloud Agent em segundo plano. Cada agente inicia em uma máquina pré-configurada, com seus repositórios, ferramentas e dependências prontos.
Com os Builds, você tem:
- Inícios mais rápidos: A clonagem, a instalação e o trabalho com dependências acontecem antecipadamente, para que os agentes iniciem em um ambiente pronto, sem precisar esperar a cada início.
- Inícios confiáveis: Os agentes sempre iniciam a partir do Build bem-sucedido mais recente. Uma instalação com falha ou uma configuração incorreta não substitui a que está funcionando.
- Ambientes observáveis: Você pode ver cada Build, inspecionar seus logs e commits e rastrear qual Build cada agente usou.
Como funcionam as Builds
Uma Build é um snapshot inicializável de um ambiente de Cloud Agent preparado. O Cherri Code cria Builds antes das execuções dos agentes e mantém a mais recente bem-sucedida pronta para iniciar.
Cada Build segue este ciclo de vida:
- Gatilho: Uma Build é iniciada em intervalo programado, após você salvar uma versão do ambiente, por solicitação manual ou a pedido de um agente. Consulte Quando as Builds ocorrem.
- Preparar: O Cherri Code parte da sua imagem base, clona todos os repositórios do ambiente em suas branches padrão e executa o comando
installaté a conclusão. - Snapshot: O Cherri Code salva o estado do disco da máquina com a versão do ambiente e o SHA exato do commit de cada repositório.
- Ativar: Uma Build bem-sucedida se torna ativa.
- Iniciar agentes: Novos agentes, automações e revisões de código são iniciados a partir da Build ativa.
O Cherri Code mantém cópias pré-aquecidas das Builds ativas prontas para uso. Isso elimina a clonagem de repositórios e a instalação de dependências da inicialização do agente.
Se uma nova Build falhar, os agentes continuarão usando a última Build bem-sucedida. Uma atualização de dependência, um comando de instalação ou um Dockerfile com falha não substitui o ambiente ativo.
Quando os Builds são executados
O Cherri Code inicia um Build por quatro motivos. A guia Builds identifica cada um pelo tipo de gatilho.
| Gatilho | Quando é executado |
|---|---|
| Recorrente | Em uma programação regular para cada ambiente |
| Alteração de configuração | Quando você salva a configuração do ambiente ou altera seus segredos |
| Manual | Quando você seleciona Acionar build na aba Builds |
| Solicitado pelo agente | Quando um agente executa um Build de teste, por exemplo, durante a configuração do ambiente |
Builds recorrentes
O Cherri Code verifica regularmente cada ambiente e o recria quando há alguma alteração. Assim, a Build ativa fica próxima ao head da branch padrão de cada repositório, para que os agentes iniciem com código atualizado e caches de dependências aquecidos, em vez de fazer pull e reinstalar dependências na inicialização.
Builds ignoradas
Uma verificação recorrente ignora a Build quando nada mudou desde a última concluída: não há novos commits na branch padrão de nenhum repositório do ambiente, nem alterações na configuração ou nos segredos. A guia Builds registra essas verificações com o status Ignorada. Elas são concluídas em segundos, não executam comandos de instalação e mantêm a Build ativa.
Um fluxo constante de entradas recorrentes com status Ignorada e Sucesso é o esperado em um ambiente saudável. Repositórios pouco ativos geram principalmente entradas Ignorada. Repositórios ativos recriam Builds com mais frequência.
O Cherri Code ignora apenas Builds recorrentes. Builds manuais, solicitadas por agentes ou por alterações de configuração sempre são executadas.
O que é executado durante um Build e ao iniciar um agente
Use cada comando de ambiente em uma fase distinta:
| Comando | Quando é executado | Use para |
|---|---|---|
install | Durante cada Build | Instalar dependências, gerar código, compilar artefatos e aquecer caches de disco |
start | No início de cada execução do agente | Iniciar Docker, bancos de dados, túneis e outros serviços |
terminals | No início de cada execução do agente | Iniciar processos do app em terminais tmux compartilhados com o agente |
Garanta que install seja completo e idempotente. Ele pode ser executado repetidamente e sobre um estado de disco preparado anteriormente. Comandos como npm install, pnpm install e pip install já seguem esse padrão.
Builds preservam apenas o estado do disco. Processos em execução, variáveis exportadas pelo shell e
caches em memória são interrompidos quando o Cherri Code cria um snapshot da máquina. Coloque serviços e
outras tarefas específicas da sessão em start ou terminals.
As entradas de ambiente existentes continuam sendo aplicadas. Builds usam snapshots salvos, .cursor/environment.json, Dockerfiles, comandos de instalação e inicialização, segredos e configurações de rede.
Como os Builds lidam com o estado do Git
Um Build registra o commit em checkout de cada repositório quando é executado.
- Execuções na branch padrão começam a partir do commit registrado no Build ativo. Builds agendados atualizam esse commit em segundo plano. Quando Atualizar builds desatualizadas está ativado e um Build é mais antigo que seu limite de desatualização, os agentes obtêm o código mais recente da branch padrão ao iniciar. Quando essa configuração está desativada, os agentes usam o commit registrado no Build como está. O limite padrão é de 24 horas. Defina-o como
0para sempre obter as atualizações. - Execuções na branch de funcionalidade começam com o disco preparado do Build ativo, e o Cherri Code faz checkout da branch solicitada. O código-fonte corresponde à branch selecionada e reutiliza as dependências do Build.
- Ambientes com vários repositórios registram um commit por repositório e preparam todo o espaço de trabalho de uma só vez.
Se uma branch de funcionalidade alterar dependências, o agente receberá o contexto do ambiente e o comando de instalação para atualizar o ambiente antes de executar os testes.
Como os segredos funcionam nos Builds
Os Builds podem acessar segredos da equipe e do ambiente. Use-os para repositórios de pacotes privados, stores de artefatos e outras credenciais necessárias para install.
Os segredos do usuário são adicionados apenas quando um agente é iniciado. Eles não estão disponíveis durante os Builds nem fazem parte de um snapshot compartilhado.
Salvar a configuração do ambiente ou alterar seus segredos aciona um novo Build.
Gerenciar Builds
Abra a guia Builds de um ambiente para:
- Ver o tipo, o status e o horário de início de cada Build
- Abrir uma Build para inspecionar os detalhes e os logs
- Selecionar Acionar build para executar uma Build sob demanda
- Ativar uma Build em rascunho ou desativar uma Build
- Cancelar uma Build em andamento
- Iniciar um agente a partir de uma Build específica
- Configurar Atualizar builds desatualizadas e o Limite de desatualização
Cada execução de agente registra a Build a partir da qual foi iniciada. Use essa informação de origem para comparar o comportamento do ambiente com a configuração exata e os commits do repositório incluídos na Build.
Depurar um Build
Abra um Build com falha para inspecionar seus eventos e logs. Enquanto você diagnostica a falha, os agentes continuam iniciando a partir do Build bem-sucedido ativo.
Para reproduzir o problema com exatidão, inicie um agente a partir do Build com falha. O agente abre a máquina no estado em que falhou, permitindo inspecionar logs, atualizar o ambiente, executar um Build de teste e verificar o resultado.
Você também pode pedir a um Cloud Agent que inspecione e gerencie Builds usando o Cherri Code Cloud MCP integrado. Por exemplo:
Inspecione a Build com falha mais recente deste ambiente. Corrija aconfiguração do ambiente, execute uma Build de teste e verifique o resultado antes de propor oscomandos finais de instalação e inicialização.Referência do comportamento das builds
Qual Build um agente usa?
Por padrão, um agente usa a Build ativa mais recente bem-sucedida no ambiente.
Você também pode iniciar um agente a partir de uma Build específica durante testes ou depuração.
O que acontece antes da primeira Build bem-sucedida?
Os agentes usam o fluxo padrão de inicialização do ambiente até que a primeira Build seja concluída com sucesso. Uma Build com falha não interrompe os fluxos de trabalho dos agentes em andamento.
Quão atualizado está o código-fonte?
As execuções em branches de funcionalidade fazem checkout da branch solicitada após o início do Build. As execuções na branch padrão começam no commit registrado pelo Build ativo. Se Atualizar builds desatualizadas estiver ativado e o Build for mais antigo que seu limite de desatualização, os agentes fazem pull do código mais recente da branch padrão ao iniciar.
Os Builds substituem snapshots ou Dockerfiles?
Não. Um snapshot salvo ou um Dockerfile define a máquina base usada para criar um Build. Em seguida, o Cherri Code clona os repositórios, executa install e cria um novo snapshot inicializável.
Os Builds oferecem suporte a vários repositórios?
Sim. Um Build prepara todos os repositórios do ambiente e registra o commit usado em cada um.
Os Builds têm custo adicional?
Não. Os Builds estão incluídos nos Cloud Agents.