Configuração declarativa

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.

Deixe o Devin fazer isso (recomendado)
Configuração manual

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.

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.”

Revise e aprove

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

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.

Ideal quando você sabe exatamente do que seu ambiente precisa ou quer controle total sobre cada etapa. É mais rápido se você já tiver seus comandos prontos.

Acesse a configuração do ambiente

Vá para Configurações > ambiente > Blueprints na barra lateral da sua organização.Se você não vir essa opção, sua organização talvez ainda esteja na configuração clássica. Consulte Migrando para a configuração declarativa para começar.

Adicione repositórios

Clique em Add na seção Repositories. Selecione os repositórios com os quais você quer que o Devin trabalhe e confirme.Os repositórios adicionados aqui são clonados no ambiente do Devin durante cada build. Você pode adicionar mais a qualquer momento.

Escreva seu blueprint

Clique em um repositório para abrir o editor de blueprint. Aqui está um exemplo simples:

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: uv run ruff check .
  - name: test
    contents: uv run pytest

Para ver mais linguagens e padrões, consulte a Biblioteca de templates.

Salve e execute a build

Clique em Save. Uma build é iniciada automaticamente (geralmente em 2–10 minutos). Acompanhe o progresso em Configurações > ambiente > Snapshots, em Current build.

Verifique

Quando a build mostrar Success, inicie uma nova sessão do Devin. 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 verificar se o ambiente está funcionando.

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:

Conceito	O que é	Analogia
Blueprint	Uma configuração YAML que descreve o que instalar e como configurar o ambiente do Devin	Dockerfile
Build	O processo que executa seu blueprint, clona repositórios e produz um snapshot	`docker build`
Snapshot	Uma imagem congelada e inicializável do ambiente da qual as sessões são iniciadas	Docker 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, além de um bloco clone opcional para blueprints no nível do repositório:

Seção	Finalidade	Quando é executada
`initialize`	Instalar ferramentas, runtimes e pacotes do sistema	Apenas durante builds. Os resultados são salvos no snapshot.
`maintenance`	Instalar/atualizar dependências do projeto, gravar configurações de credenciais	Durante builds. Exibida ao agente no início da sessão (não executada automaticamente).
`knowledge`	Informaçõ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.
`clone`	Substituir os padrões de clonagem do Git para o repositório (apenas no nível do repositório)	Aplicado durante a etapa de clonagem da build.

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 é exibida ao agente no início da sessão para que ele possa executá-las novamente se as dependências tiverem mudado (por exemplo, após obter o código mais recente). Os comandos não são executados automaticamente no início da sessão, mas ainda assim 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. clone (apenas no nível do repositório) substitui os padrões que o Devin usa ao clonar o repo no snapshot — por exemplo, fazer checkout de uma branch diferente da padrão (ref), alterar o destino da clonagem (path) ou pular submódulos ou objetos LFS. Todos os campos são opcionais. Consulte Referência de blueprints → clone para ver a lista completa de campos.

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.

YAML com vários documentos: O editor de blueprint oferece suporte a YAML com vários documentos usando o separador ---. Isso permite organizar blueprints complexos em seções lógicas em um único editor.

Para ver a especificação completa dos campos (tipos de etapa, 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ível	Onde configurar	O que colocar aqui
Organização	Configurações > Ambiente > Blueprints > Configuração em nível da organização	Ferramentas compartilhadas por todos os repos: runtimes de linguagem, gerenciadores de pacotes, autenticação do Docker
Repositório	Configurações > Ambiente > Blueprints > [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. Enterprise blueprint, if configured (runs in ~):
   a. initialize
   b. maintenance
2. Org blueprint (runs in ~):
   a. initialize
   b. maintenance
3. Clonar todos os repositórios (até 10 simultâneos).
   O blueprint de cada repo pode sobrescrever os padrões de clonagem via
   bloco `clone` (branch/tag, profundidade, submódulos, LFS, etc.).
4. For each configured repo, in the order shown in Configurações
   (runs in ~/repos/<repo-name>):
   a. initialize
   b. maintenance
5. Health check, then snapshot is saved

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:

O código mais recente é obtido do(s) repo(s) relevante(s).
Os comandos de maintenance (Enterprise, org e repo) são apresentados ao agente como contexto — não são executados automaticamente. O agente pode executá-los novamente se detectar que as dependências mudaram desde o último build.
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

Gatilho	Descrição
Salvar um blueprint	Criar, atualizar ou excluir um blueprint
Adicionar ou remover um repositório	Qualquer alteração na lista de repositórios
Adicionar um segredo ao repositório	Novos segredos exigem um rebuild para ficarem disponíveis
Gatilho manual	Clicar em Build snapshot na UI
Atualização periódica	Automática, aproximadamente a cada 24 horas
Sugestão do Devin	O 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

Status	Significado
Success	Todas as etapas foram concluídas. O snapshot está pronto.
Partial	Algumas 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.
Failed	Falha crítica (a configuração da org ou do Enterprise falhou). O snapshot não é utilizável.
Cancelled	Foi 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:

State	Meaning
Configured	Tem um blueprint com instruções de inicialização/manutenção/Knowledge. Totalmente configurado no snapshot.
Included	Clonado no snapshot, mas sem blueprint personalizado. Devin pode acessar o código.
Available	Conectado à 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 na aba Segredos no editor de blueprint.

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. Coloque as etapas que gravam credenciais em maintenance para que sejam atualizadas durante builds periódicos. 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.

GitHub Actions

Em vez de escrever scripts de shell para instalar ferramentas e runtimes, você pode referenciar GitHub Actions diretamente no blueprint. Devin baixa e executa a GitHub Action durante a build, da mesma forma que os runners de CI do GitHub executam as etapas da action.

initialize:
  - name: Install Python 3.12
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

Isso é especialmente útil para ações de configuração de linguagens, como setup-python, setup-node e setup-go, que fazem automaticamente o gerenciamento de versões e a configuração do PATH. Para detalhes de sintaxe, exemplos e limitações, consulte GitHub Actions em blueprints.

Monorepos

Você pode executar comandos em subdiretórios usando subshells ou criar blueprints dedicados com escopo de workspace para packages individuais. Devin também oferece suporte a entradas no Knowledge por package, para que cada workspace tenha seus próprios comandos de lint, test e build. Consulte Workspaces e monorepos para obter instruções de configuração e exemplos.

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 Configurações > Ambiente > Snapshots, encontre o build no histórico (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 versionados no Git

Você pode armazenar blueprints como arquivos .devin/blueprint.yaml diretamente no seu repositório. Após fazer merge das alterações, chame a API de sincronização (ou clique em Sync na UI) para atualizar o blueprint e, em seguida, acionar um build. Isso oferece o mesmo workflow de revisão de código que você usa para o código da aplicação, com a sincronização automatizada por meio de uma etapa de CI. Consulte Git-backed blueprints para obter instruções de configuração e mais detalhes.

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

Verifique os logs da build para identificar a falha
Atualize o blueprint relevante
Salve (uma nova build é acionada automaticamente)
Monitore os logs da nova build
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

Builds diferenciais

Acelere os builds reconstruindo apenas os workspaces cujos blueprints foram alterados.

GitHub Actions em blueprints

Use GitHub Actions para instalar linguagens, ferramentas e SDKs sem escrever scripts de shell.

Workspaces e monorepos

Subshells, escopos de workspace e entradas de Knowledge para repositórios com vários pacotes.

Referência de blueprints

Referência completa dos campos: tipos de etapa, 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.

Blueprints versionados no Git

Armazene blueprints no seu repo como .devin/blueprint.yaml e sincronize pela API ou pela UI.

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.

​Primeiros passos

​Como funciona

​Seções do blueprint

​Escopo dos blueprints

​Builds e sessões

​O snapshot

​Como os builds funcionam

​Como as sessões funcionam

​O que aciona um build

​Status de builds

​Gerenciando seu ambiente

​Estados dos repositórios

​Segredos

​Vários repositórios

​GitHub Actions

​Monorepos

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

​Blueprints versionados no Git

​Solução de problemas em builds

​A etapa de inicialização falhou

​Falha ao clonar o repo

​Falha na etapa de manutenção

​Tempo limite de build

​Refinando as correções

​Próximas etapas

Builds diferenciais

GitHub Actions em blueprints

Workspaces e monorepos

Referência de blueprints

Biblioteca de templates

Blueprints versionados no Git

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

Gerenciamento de ambiente Enterprise

Primeiros passos

Como funciona

Seções do blueprint

Escopo dos blueprints

Builds e sessões

O snapshot

Como os builds funcionam

Como as sessões funcionam

O que aciona um build

Status de builds

Gerenciando seu ambiente

Estados dos repositórios

Segredos

Vários repositórios

GitHub Actions

Monorepos

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

Blueprints versionados no Git

Solução de problemas em builds

A etapa de inicialização falhou

Falha ao clonar o repo

Falha na etapa de manutenção

Tempo limite de build

Refinando as correções

Próximas etapas