Pular para o conteúdo principal
Soluções para falhas comuns de build, respostas para perguntas frequentes e um guia para migrar da configuração interativa legada.
Para a configuração geral do ambiente, consulte Configuração do ambiente. Para detalhes de sintaxe, consulte a Referência de YAML.

​
Depuração de falhas de build

​
Etapa 1: Verifique o status da build

Acesse Configurações > Ambiente do Devin > Histórico de builds. Sua build exibirá um destes status:
StatusO que significaO que fazer
SucessoTudo funcionouNada — sua imagem da máquina está pronta
ParcialA build principal foi concluída, mas alguns repos falharamVerifique quais repos falharam; as sessões deles podem ter problemas
FalhaA própria build falhouVerifique os logs da etapa com falha
CanceladoUma build mais recente substituiu estaNormal — inicie uma build mais recente, se necessário
IgnoradoNenhuma alteração de configuração foi detectadaNada — nenhuma build foi necessária

​
Etapa 2: Leia os logs de build

Os logs de build são organizados por etapa:
  1. Configuração compartilhada — comandos do Enterprise + de nível da organização
  2. Clone — clonagem do repositório
  3. Configuração do repo — comandos por repositório
  4. Finalização — verificação de integridade e criação da imagem
Procure o primeiro erro nos logs. Os erros seguintes geralmente são falhas em cascata causadas pelo primeiro.
Se você usou a forma expandida com campos name, os logs mostrarão exatamente qual etapa falhou. Esse é um dos principais benefícios de nomear suas etapas: 
# Sem nomes — difícil de depurar
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  npm install -g pnpm

# Com nomes — fácil de identificar falhas
initialize:
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh
  - name: Install pnpm
    run: npm install -g pnpm

​
Etapa 3: Identifique o padrão da falha

​
Falhas de clonagem

Sintoma: A build falha durante a clonagem. Causas comuns:
  • O acesso ao repositório não está configurado — verifique Configurações do Enterprise > Integrações
  • Um repo privado requer um token de autenticação
  • O repositório foi renomeado ou excluído
  • Problema de conectividade de rede (é necessário usar VPN ou proxy)
Correção: Verifique se o Devin tem acesso ao repositório em configurações de integração. Para registries privados, garanta que as credenciais estejam configuradas em segredo.

​
Falhas na instalação de dependências

Sintoma: O build falha durante a configuração do repo, geralmente em npm install, pip install ou algo semelhante. Causas comuns:
  • O registro privado de pacotes exige autenticação — adicione o token em segredo
  • Conflito entre versões de pacotes — fixe versões específicas
  • Timeout de rede — verifique se a VPN é necessária
  • URL do registro configurada incorretamente
Correção: Adicione a autenticação do registro na seção maintenance. Consulte Exemplos de configuração para ver padrões de registro privado.

​
Falhas de timeout

Sintoma: O build parece travado e depois falha. Causas comuns:
  • Prompt interativo aguardando entrada — adicione a flag -y e use DEBIAN_FRONTEND=noninteractive
  • Instalação de dependências muito grande levando tempo demais
  • O comando excede o timeout de 1 hora
Correção: Adicione flags não interativas a todos os comandos de instalação. Mova instalações lentas que só precisam ser feitas uma vez para initialize, para que sejam executadas apenas durante os builds (não em toda sessão). 
# Ruim — ficará travado aguardando entrada
initialize: |
  sudo apt-get install libpq-dev

# Bom — não interativo
initialize: |
  sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq libpq-dev

​
Erros de permissão

Sintoma: “Permissão negada” nos logs. Causas comuns:
  • Falta de sudo para instalar pacotes do sistema
  • Tentativa de gravar em diretórios protegidos
  • Arquivo de uma build anterior pertencente a outro usuário
Correção: Use sudo para operações no nível do sistema (apt-get, gravar em /etc/, etc.). Para gerenciadores de pacotes no nível do usuário (npm, pip, cargo), sudo geralmente não é necessário.

​
Erros de “comando não encontrado”

Sintoma: Uma ferramenta instalada em initialize não fica disponível em maintenance ou em etapas posteriores. Causas comuns:
  • A ferramenta é instalada em um diretório que não está no PATH
  • Alterações no perfil do shell (.bashrc) não são carregadas nas etapas seguintes
Correção: Adicione o diretório da ferramenta ao PATH via $ENVRC: 
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC

​
Etapa 4: Faça iterações

Após identificar o problema:
  1. Corrija sua configuração YAML
  2. Salve — um novo build será iniciado automaticamente
  3. Verifique os logs do novo build
Teste os comandos primeiro. Antes de adicionar um comando à sua configuração, tente executá-lo em uma sessão do Devin para garantir que funcione. Isso é mais rápido do que esperar um ciclo completo de build.

​
Referência rápida de erros comuns

ErroCausa provávelCorreção
command not foundFerramenta não instalada ou fora do PATHAdicione a initialize ou ao PATH via $ENVRC
Permission deniedFalta de sudoUse sudo apt-get install para pacotes do sistema
npm ERR! 404Pacote privado, sem autenticaçãoAdicione o token de autenticação do registro em maintenance (exemplos)
E: Unable to locate packageapt-get update não foi executado antesAdicione sudo apt-get update -qq antes de apt-get install
TimeoutInstalação lenta ou prompt interativoMova para initialize; adicione -y e DEBIAN_FRONTEND=noninteractive
Arquivos de configuração vazios após o início da sessãoCredenciais gravadas em initializeMova as etapas de credenciais para maintenance
Build concluída com sucesso, mas a sessão está corrompidaO comando maintenance falha no início da sessãoTeste manualmente os comandos de maintenance em uma sessão

​
Migrando da configuração interativa

Se você estiver usando a configuração interativa legada no momento (o assistente passo a passo), poderá migrar para a configuração declarativa para ter melhor reprodutibilidade e suporte a vários repositórios.

​
Como a migração funciona

A configuração legada e a configuração declarativa produzem, cada uma, sua própria imagem da máquina. As sessões usam uma ou outra — nunca uma combinação das duas. Um controle no nível da org chamado “Use legacy machine snapshot” define qual imagem é usada:
  • Controle ATIVADO (padrão) — todas as sessões usam o snapshot legado. Sem interrupções.
  • Controle DESATIVADO — todas as sessões usam o snapshot declarativo.
Isso significa que você pode configurar e testar a configuração declarativa em paralelo, enquanto todos os outros continuam trabalhando com o snapshot legado.

​
Etapas da migração

1

Prepare a configuração

Anote os comandos da sua configuração interativa atual — você vai mapeá-los para seções do YAML:
Etapa do assistente legadoEquivalente declarativo
Git pullAutomático (integrado)
Configurar segredosegredo (sem alterações)
Instalar dependênciasseção initialize
Manter dependênciasseção maintenance
Configurar lintentrada knowledge com o nome lint
Configurar testesentrada knowledge com o nome test
Executar o app localmenteentrada knowledge com o nome startup
Observações adicionaisentrada knowledge com o nome notes
2

Escreva seu YAML

Vá para Configurações > Ambiente do Devin e selecione seu repositório. Mapeie seus comandos legados:
# Legado "Install Dependencies" → initialize
initialize: |
  nvm use 18
  npm install -g pnpm

# Legado "Maintain Dependencies" → maintenance
maintenance: |
  pnpm install

# Legado "Set up lint/tests/app/notes" → knowledge
knowledge:
  - name: lint
    contents: |
      pnpm lint
  - name: test
    contents: |
      pnpm test
  - name: startup
    contents: |
      pnpm dev (port 3000)
  - name: notes
    contents: |
      Sempre execute o lint antes de fazer commit.
Ou simplesmente inicie uma sessão do Devin e peça para ele configurar o repo — o Devin pode gerar a configuração automaticamente para você.
3

Salve e aguarde o build

Salve sua configuração. Um build é iniciado automaticamente. Acompanhe o progresso em Histórico de build. Builds são gratuitos — eles não consomem ACUs.
4

Teste antes de alternar

Antes de migrar todo mundo, teste a configuração declarativa em sessões individuais usando o override manual. Isso permite que você (ou quem estiver iterando na configuração) use o snapshot declarativo enquanto todos os demais permanecem no snapshot legado.Itere na configuração até que a configuração declarativa alcance paridade total com seu ambiente legado.
5

Faça a transição

Quando estiver confiante, desative “Use legacy machine snapshot” nas Configurações da sua org. Todas as novas sessões passarão a usar o snapshot declarativo.
Fluxos de autenticação interativos (por exemplo, login no navegador com AWS SSO, fluxos OAuth que exigem um navegador) não podem ser replicados no formato declarativo. Se sua configuração legada usa autenticação baseada em navegador, você precisará converter esses fluxos para alternativas sem interface gráfica (Chaves de API, tokens de conta de serviço etc.) antes de migrar. Adicione credenciais em segredo e faça referência a elas na sua seção maintenance.

​
Migração do Enterprise

Para empresas com várias organizações:
  1. Configure primeiro o YAML no nível do Enterprise — infraestrutura compartilhada, como VPN, certificados e configurações de proxy.
  2. Migre uma org por vez. Cada org tem seu próprio controle legado, então você pode migrar progressivamente sem afetar outras equipes.
  3. Considere uma org de teste. Para grandes empresas, crie uma organização de teste dedicada para validar a configuração declarativa antes de implantá-la nas org de produção.
  4. Use o Devin em escala. O Devin pode configurar repos por meio de sessões paralelas — inicie uma sessão por repo, e o Devin gerará automaticamente propostas de configuração. Isso funciona bem para integrar de 10 a mais de 100 repos.

​
O que acontece com meu snapshot antigo?

Seu snapshot antigo é mantido. Se o novo build declarativo falhar, Devin volta para o snapshot bem-sucedido mais recente (que pode ser o snapshot legado). Você também pode restaurar snapshots anteriores pelo Histórico de build.

​
Principais diferenças

RecursoLegado (interativo)Declarativo (YAML)
ReprodutibilidadeCom estado — snapshots acumulam alterações ao longo do tempoTotalmente reproduzível a partir do YAML
Multi-repoUm repo por vezVários repos em um build com clonagem simultânea
ManutençãoEtapas manuais de “maintain dependencies”Automática — maintenance é executado no início da sessão
Camadas de Enterprise/orgSem suporteHierarquia de 3 níveis (Enterprise → Org → Repo)
Sugestões do DevinApenas no assistenteDurante a sessão — Devin pode sugerir atualizações de configuração
CustoSessões do assistente consumiam ACUsSessões de configuração ~1–3 ACUs; builds são gratuitos

​
Perguntas frequentes

​
Geral

O que acontece se eu executar uma sessão em um repo que não está configurado? O Devin ainda vai funcionar — ele só vai precisar entender seu projeto do zero todas as vezes. Isso significa gastar tempo instalando dependências, descobrindo como fazer o build e os testes, e deduzindo convenções. As sessões demoram mais e custam mais ACUs. Ao configurar seu ambiente, o Devin inicia cada sessão já pré-configurado e pronto para uso. Quanto tempo um build leva? Normalmente, de 5 a 15 minutos, dependendo do número de repos e do tamanho das dependências. Os builds atingem o tempo limite após 2 horas. Quanto isso custa? Os builds são gratuitos — não consomem ACUs. Se você usar uma sessão do Devin para configurar um repo (por exemplo, pedindo ao Devin para gerar sua configuração), essa sessão normalmente custa de 1 a 3 ACUs. Depois que a configuração é salva, todos os builds subsequentes gerados a partir dela são gratuitos. Posso usar a configuração legada e a declarativa ao mesmo tempo? Uma org usa um modo por vez, controlado pelo controle “Use legacy machine snapshot”. Você pode configurar a abordagem declarativa em paralelo enquanto o controle ainda estiver ativado (modo legado) e depois mudar quando estiver tudo pronto. Consulte o guia de migração para mais detalhes. Posso testar a configuração declarativa sem afetar outros usuários? Sim. Use o override manual em sessões individuais para usar temporariamente o snapshot declarativo enquanto todos os outros continuam no snapshot legado. Para ambientes Enterprise, você também pode criar uma organização de teste dedicada. O que acontece se meu build falhar? O Devin usa o snapshot bem-sucedido mais recente. Um build com falha não interrompe as sessões existentes. Quando devo usar initialize em vez de maintenance? Use initialize para instalações únicas de ferramentas (apt-get install, configuração do runtime da linguagem, ferramentas de CLI globais). Use maintenance para instalação de dependências que precisam se manter atualizadas (npm install, pip install, uv sync). Como adiciono variáveis de ambiente? Escreva-as em $ENVRC: 
initialize: |
  echo "MY_VAR=value" >> $ENVRC
Posso instalar pacotes do sistema? Sim, use sudo apt-get install na seção initialize. Sempre use DEBIAN_FRONTEND=noninteractive e a flag -y para evitar prompts interativos. E se eu precisar de versões diferentes do Node para repos diferentes? Use o nvm na configuração no nível do repo: 
initialize: |
  nvm install 18
  nvm use 18
Fluxos de autenticação interativos são compatíveis? Não. A autenticação baseada em navegador (como login com AWS SSO ou fluxos OAuth que exigem uma janela do navegador) não pode ser reproduzida no formato declarativo. Converta isso para alternativas sem interface gráfica — use chaves de API, tokens de conta de serviço ou outras abordagens baseadas em credenciais e armazene-as em segredo. No momento, não há solução alternativa para workflows que exigem estritamente SSO baseado em navegador. Esses repos devem continuar usando a configuração interativa até que alternativas sem interface gráfica estejam disponíveis.

​
Específico da build

O que significa “sucesso parcial”? A build principal (Enterprise + configuração da org + clonagem) foi concluída com sucesso, mas uma ou mais configurações no nível do repositório falharam. As sessões funcionarão, mas os repos com falha podem não ter as dependências instaladas corretamente. Por que minha build foi cancelada? Uma build mais recente foi acionada antes de a sua ser concluída. Apenas a build mais recente é executada; builds mais antigas na fila são canceladas automaticamente. Alterar a configuração de um repo refaz tudo? Sim — uma build cria uma única imagem da máquina com todos os repos configurados. Qualquer alteração em qualquer configuração aciona uma reconstrução completa. Posso voltar para uma build anterior? Sim, em Histórico de build nas Configurações do ambiente. Você pode restaurar qualquer snapshot anterior bem-sucedido. Quantos repos posso incluir? Até 10 repos são clonados simultaneamente durante uma build. Não há um limite rígido para o total de repos, mas quanto mais repos, mais longa a build. Devin pode configurar repos em escala por meio de sessões paralelas — inicie uma sessão por repo para 10–100+ repos.

​
Específico do Enterprise

Quem pode editar a configuração no nível Enterprise? Apenas administradores do Enterprise. Administradores de org podem editar a configuração em nível da organização e em nível de repo. Membros regulares podem editar a configuração em nível de repo se tiverem a permissão ManageOrgSnapshots. Consulte Enterprise Environment Setup para ver a tabela completa de permissões. Alterar a configuração do Enterprise faz rebuild de todas as org? Sim. Uma alteração no nível Enterprise aciona builds para todas as organizações no Enterprise. Orgs diferentes podem ter configurações diferentes? Sim. Cada org tem sua própria configuração em nível da organização e configurações em nível de repo. A configuração do Enterprise é compartilhada e aditiva — ela é executada antes da configuração de cada org. Configurações de níveis mais baixos podem sobrescrever as de níveis mais altos? Não. A hierarquia (Enterprise → Org → Repo) é estritamente aditiva. Os comandos de cada nível são executados em sequência após a conclusão do nível anterior. Níveis mais baixos não podem impedir nem modificar o que níveis mais altos configuram. A configuração no nível Enterprise pode clonar repositórios? Não. A clonagem de repositórios exige acesso em nível de org. A configuração no nível Enterprise pode instalar ferramentas e infraestrutura compartilhadas, mas a clonagem de repo deve ser configurada no nível da org ou da repo.

​
Limitações conhecidas

  • Sem prévia/sandbox de build — toda alteração na configuração aciona um build completo. Teste primeiro os comandos em uma sessão.
  • Configuração serial de repo — a configuração no nível do repositório é executada em um repo por vez (em ordem alfabética). Um grande número de repos resulta em builds mais longos.
  • Sem lógica condicional em YAML — o formato não oferece suporte a if/else. Use condicionais de shell nos comandos, se necessário (por exemplo, [ -f package.json ] && npm install).
  • Sem busca nos logs de build — é preciso rolar os logs de build manualmente. Use etapas nomeadas para facilitar a identificação de falhas.

​
Próximas etapas