Pular para o conteúdo principal

​
Primeiros passos

Pré-requisitos: o Devin precisa ter acesso aos seus repositórios antes que você possa configurar o ambiente dele. Se você ainda não configurou sua integração com o Git, consulte Antes de começar para ver as etapas de configuração. Usuários do Enterprise também precisam conceder a cada org acesso aos seus repos em Enterprise Settings > Repository Permissions.
Ainda está na configuração clássica? Você pode migrar para a configuração declarativa a qualquer momento. O Devin pode fazer a maior parte dessa migração para você. Consulte Migrando para a configuração declarativa.
Ideal para a maioria dos usuários. O Devin analisa seu projeto, identifica quais ferramentas e dependências são necessárias e gera o blueprint para você. Basta revisar e aprovar.
1

Inicie uma sessão do Devin

Abra uma nova sessão e peça ao Devin para configurar o repositório. Por exemplo: “Configure seu ambiente para este repo.”
2

Revise e aprove

O Devin propõe um blueprint. Você verá cards de sugestão na sua timeline. Revise-os e clique em Approve.
3

Verifique

Quando a build for concluída, inicie uma nova sessão. O Devin será iniciado a partir do novo snapshot com tudo pré-configurado. Tente pedir ao Devin para executar seus comandos de lint ou teste para confirmar que tudo funciona.
O restante deste guia detalha o caminho manual. Ele também é útil para entender o que o Devin gerou caso você tenha usado o caminho recomendado.

​
Como funciona

A configuração declarativa usa três conceitos:
ConceitoO que éAnalogia
BlueprintUma configuração YAML que descreve o que instalar e como configurar o ambiente do DevinDockerfile
BuildO processo que executa seu blueprint, clona repositórios e produz um snapshotdocker build
SnapshotUma imagem congelada e inicializável do ambiente da qual as sessões são iniciadasDocker image
Blueprints descrevem o que você quer. Você os cria e edita na interface de Configurações. Builds executam seus blueprints para produzir snapshots. Os builds são executados automaticamente quando você salva um blueprint e periodicamente (~a cada 24 horas) para manter as dependências atualizadas. Snapshots são a base da qual as sessões são iniciadas. Cada organização tem um snapshot ativo. Cada sessão inicia a partir de uma nova cópia. As alterações da sessão não são persistidas de volta no snapshot.

​
Seções do blueprint

Um blueprint tem três seções:
SeçãoFinalidadeQuando é executada
initializeInstalar ferramentas, runtimes e pacotes do sistemaApenas durante builds. Os resultados são salvos no snapshot.
maintenanceInstalar/atualizar dependências do projeto, gravar configurações de credenciaisDurante builds + no início de cada sessão
knowledgeInformações de referência para Devin (comandos de lint, teste e build)Não é executada. Carregada no contexto do Devin no início da sessão.
initialize é para coisas que só precisam acontecer uma vez: runtimes de linguagem, pacotes do sistema e ferramentas CLI globais. maintenance é para a instalação de dependências que devem permanecer atualizadas. Ela é executada durante builds e novamente no início de cada sessão, após obter o código mais recente, então os comandos devem ser rápidos e incrementais (use npm install, não npm ci). knowledge contém informações de referência e não é executada. É assim que você informa ao Devin os comandos corretos para lint, testes e build. Mantenha as entradas enxutas e focadas em comandos executáveis.
Knowledge aqui vs. o recurso Knowledge do produto: A seção knowledge no seu blueprint serve para referências curtas de comandos vinculadas ao ambiente. Para documentação de arquitetura, convenções e fluxos de trabalho da equipe, use o recurso independente Knowledge.
Para ver a especificação completa dos campos (tipos de etapa, suporte a GitHub Actions, variáveis de ambiente, segredos e anexos de arquivos), consulte a Referência de blueprints.

​
Escopo dos blueprints

Você pode definir blueprints em dois níveis:
NívelOnde configurarO que colocar aqui
OrganizaçãoConfigurações > Configuração do ambiente > Configuração em nível da organizaçãoFerramentas compartilhadas por todos os repos: runtimes de linguagem, gerenciadores de pacotes, autenticação do Docker
RepositórioConfigurações > Configuração do ambiente > [nome do repo]Configuração específica do projeto: npm install, comandos de lint/test/build
Os blueprints são aditivos: os blueprints de repo se baseiam no blueprint da organização. O maintenance de um repo pode usar ferramentas instaladas pelo initialize da organização. Se apenas um repo precisar de uma ferramenta, coloque-a no blueprint desse repo. Se todos os repos precisarem dela, coloque-a no blueprint da organização.
Usuários do Enterprise: Há um terceiro nível, o blueprint Enterprise, que se aplica a todas as organizações. Consulte a visão geral do ambiente Enterprise para mais detalhes.

​
Builds e sessões

​
O snapshot

Sua organização tem um snapshot ativo: uma imagem de VM com suas ferramentas, repositórios e dependências pré-instalados. Todos os repositórios configurados são clonados e preparados nessa única imagem. Cada sessão é iniciada a partir de uma nova cópia.

​
Como os builds funcionam

Um build cria um novo snapshot executando seus blueprints em sequência: 
1. Blueprint Enterprise, se configurado (executado em ~):
   a. initialize
   b. maintenance
2. Blueprint da org (executado em ~):
   a. initialize
   b. maintenance
3. Clonar todos os repositórios (até 10 simultâneos)
4. Para cada repo configurado, na ordem exibida em Configurações
   (executado em ~/repos/<repo-name>):
   a. initialize
   b. maintenance
5. Verificação de integridade e, então, o snapshot é salvo
As camadas são aditivas: comandos específicos do repo podem usar ferramentas instaladas pela org ou pelo blueprint da Enterprise. Níveis inferiores não podem sobrescrever o que um nível superior configurou. Builds normalmente levam de 5 a 15 minutos. Etapas individuais têm tempo limite de 1 hora.

​
Como as sessões funcionam

Cada sessão inicia uma cópia nova do snapshot. Quando a sessão termina, todas as alterações são descartadas. No início da sessão:
  1. Execuções de maintenance do Enterprise e em nível da organização (em ~).
  2. O código mais recente é obtido do(s) repo(s) relevante(s).
  3. O maintenance desse repo é executado novamente para captar alterações nas dependências desde o último build.
  4. As entradas de Knowledge desse repo são carregadas no contexto do Devin.
Knowledge é por repositório. Se você tiver 5 repositórios configurados, o Devin verá apenas as entradas de Knowledge daquele em que estiver trabalhando.

​
O que aciona um build

GatilhoDescrição
Salvar um blueprintCriar, atualizar ou excluir um blueprint
Adicionar ou remover um repositórioQualquer alteração na lista de repositórios
Adicionar um segredo ao repositórioNovos segredos exigem um rebuild para ficarem disponíveis
Gatilho manualClicar em Build ou Rebuild na interface
Atualização periódicaAutomática, aproximadamente a cada 24 horas
Sugestão do DevinO Devin propõe uma alteração no blueprint durante uma sessão
Apenas um build é executado por vez. Novos gatilhos cancelam qualquer build na fila e iniciam outro do zero.

​
Status de builds

StatusSignificado
SuccessTodas as etapas foram concluídas. O snapshot está pronto.
PartialAlgumas etapas no nível do repositório falharam, mas o snapshot é utilizável. Os repositórios que tiveram sucesso funcionam normalmente; os repositórios que falharam precisam ter seus blueprints corrigidos.
FailedFalha crítica (a configuração da org ou do Enterprise falhou). O snapshot não é utilizável.
CancelledFoi substituído por um build mais recente ou cancelado manualmente.
Um build partial ainda produz um snapshot funcional. Se um de cinco repositórios tiver um blueprint com problema, os outros quatro estarão totalmente funcionais.
Build falhando? Consulte Solução de problemas de builds para um guia de depuração passo a passo.

​
Gerenciando seu ambiente

​
Estados dos repositórios

Os repositórios aparecem em três estados nas Configurações do ambiente:
StateMeaning
ConfiguredTem um blueprint com instruções de inicialização/manutenção/Knowledge. Totalmente configurado no snapshot.
IncludedClonado no snapshot, mas sem blueprint personalizado. Devin pode acessar o código.
AvailableConectado à org, mas não adicionado ao ambiente. Não clonado.
Included vs. configured: Um repo “included” é clonado para que Devin possa acessar o código, mas não tem comandos de configuração personalizados. Um repo “configured” tem instruções explícitas de inicialização/manutenção/Knowledge.

​
Segredos

Referencie os segredos com a sintaxe $VARIABLE_NAME. Adicione-os em Configurações > Segredos. 
maintenance:
  - name: Configure private registry
    run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
Os segredos estão disponíveis como variáveis de ambiente durante builds e sessões. Eles são removidos antes de o snapshot ser salvo, mas, se um comando gravar um valor secreto em um arquivo de configuração durante initialize, esse valor persistirá no snapshot. Sempre grave as credenciais em maintenance. Para ver detalhes sobre os escopos e o comportamento dos segredos, consulte a Referência de blueprints.

​
Vários repositórios

Cada repo recebe seu próprio blueprint. Durante um build, todos os repositórios são configurados no mesmo snapshot, clonados em diretórios separados, com as dependências instaladas de forma independente. Se dois repositórios instalarem versões diferentes de uma ferramenta global ou modificarem arquivos compartilhados (como ~/.bashrc), o que for executado por último prevalece. Coloque as instalações de ferramentas compartilhadas no blueprint de nível da organização para evitar conflitos.

​
Monorepos

Para um monorepo, escreva um único blueprint abrangendo todos os subprojetos. Use subshells para executar comandos em subdiretórios: 
maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)
Os parênteses (cd ... && ...) são executados em um subshell para que o diretório de trabalho volte ao estado original na próxima etapa.

​
Fixação e atualizações automáticas

Por padrão, o Devin usa o snapshot do build bem-sucedido mais recente. Fixar permite bloquear o uso de um snapshot de um build específico. Isso é útil quando um novo build introduz uma regressão ou quando você quer congelar o ambiente para um lote de sessões. Para fixar: Acesse Snapshot build history, encontre o build (deve ser success ou partial, com menos de 7 dias) e clique em Pin. Enquanto estiver fixado, as atualizações periódicas são puladas e a interface mostra Auto-updates paused. Para remover a fixação: Clique em Resume auto-updates. O Devin muda para o build bem-sucedido mais recente.

​
Blueprints baseados em Git

No momento, blueprints baseados em Git ainda não são compatíveis. Esse recurso estará disponível em breve. Você poderá armazenar blueprints no seu repositório e fazer com que as builds sejam acionadas automaticamente quando eles forem alterados. Por enquanto, configure os blueprints pela UI.

​
Solução de problemas em builds

​
A etapa de inicialização falhou

Causas comuns: erro de digitação em um comando de shell, pacote indisponível, tempo limite de rede, referência incorreta a uma GitHub Action. Correção: Verifique os logs de build para identificar o erro exato. Atualize initialize no seu blueprint e salve. Uma nova build é acionada automaticamente.

​
Falha ao clonar o repo

Causas comuns: Devin não tem acesso ao repo, o repo foi renomeado/movido/excluído, problema temporário de rede. Correção: Verifique o acesso ao repo nas configurações do seu provedor Git. Remova e adicione o repo novamente se ele tiver sido renomeado.

​
Falha na etapa de manutenção

Causas comuns: conflito de dependências, biblioteca de sistema ausente, falta de espaço em disco, lock file fora de sincronização. Correção: Verifique os logs do pacote/comando que falhou. Atualize maintenance ou initialize para instalar as dependências ausentes ou corrija o lock file no seu repositório.

​
Tempo limite de build

Cada etapa tem um limite de tempo de 1 hora. Causas comuns: compilar grandes dependências nativas a partir do código-fonte (use binários pré-compilados), baixar artefatos grandes, comandos que ficam bloqueados aguardando entrada (todos os comandos devem ser executados sem interação).

​
Refinando as correções

  1. Verifique os logs da build para identificar a falha
  2. Atualize o blueprint relevante
  3. Salve (uma nova build é acionada automaticamente)
  4. Monitore os logs da nova build
  5. Repita até que a build seja concluída com sucesso
Você não precisa esperar uma build com falha terminar. Salvar uma nova configuração cancela qualquer build na fila e inicia uma nova do zero.

​
Próximas etapas

Referência de blueprints

Referência completa dos campos: tipos de etapa, GitHub Actions, variáveis de ambiente, segredos e anexos de arquivo.

Biblioteca de templates

Blueprints prontos para copiar e colar para Python, Node.js, Go, Java, Ruby, Rust e padrões avançados.

Migração da configuração clássica

Guia passo a passo para migrar do assistente interativo para blueprints declarativos.

Gerenciamento de ambiente Enterprise

Gerenciamento de ambiente em toda a Enterprise: hierarquia de 3 níveis, segredos e configuração entre organizações.