Skip to main content
Blueprints têm três níveis — repositório, organização e Enterprise — e a pergunta mais comum é em qual nível isso deve ficar? Esta página responde a isso acompanhando uma empresa fictícia, ACME Corp, em três estágios de crescimento. Cada estágio apresenta exatamente um novo problema, e cada problema é resolvido pelo nível seguinte. Vá direto para o estágio que mais se parece com a sua empresa.
A regra prática, de antemão: blueprints de repositório instalam dependências do projeto, blueprints da organização instalam tudo o que é compartilhado por mais de um repositório, e blueprints Enterprise instalam tudo o que toda organização precisa ter. Os níveis são aditivos e são executados de cima para baixo: enterprise → organização → clonar os repositórios → repositório.

Etapa 1: um repositório

A ACME tem um produto: acme-web, uma aplicação em Rails com Postgres e Redis. Dois engenheiros, um repositório. Ainda não há nada para compartilhar, então tudo fica no blueprint de repositório. Eles adicionam o repositório em Configurações > Ambiente > Blueprints > Adicionar, abrem o editor dele e escrevem:
acme-web (repository blueprint)
Essa é toda a configuração. Ao salvá-la, um build é executado, e toda sessão é iniciada com Ruby instalado, Postgres em execução, gems instaladas e as migrações do banco de dados aplicadas. Por que ainda não há um blueprint da organização? Um blueprint da organização que atende a apenas um repositório é só indireção. Espere até que um segundo repositório precise da mesma coisa.
A ACME não escreveu isso manualmente. Ela pediu ao Devin “configure seu ambiente para este repositório”, revisou o card de sugestão e clicou em Approve. Veja Primeiros passos.

Etapa 2: vários repositórios com dependências compartilhadas

Dois anos depois, a ACME tem cinco repositórios: Este é o caso interessante, porque os repositórios não são independentes: não é possível fazer nenhum trabalho útil em acme-portal a menos que acme-devtools esteja instalado e acme-sso esteja em execução. Surgem duas perguntas.

”Um blueprint por aplicação ou apenas um para a CLI de desenvolvimento?”

Ambos — cada um tem uma função diferente. O Devin cria um snapshot contendo todos os repositórios configurados, então não é uma escolha de um ou outro:
  • Adicione os cinco repositórios ao ambiente para que todos sejam clonados no snapshot.
  • Coloque a configuração compartilhada entre repositórios uma única vez no blueprint da organização: runtimes de linguagem, Docker, nomes de host locais e credenciais para o registro interno.
  • Dê a cada repositório seu próprio blueprint de repositório para suas dependências e suas entradas de knowledge (comandos de lint, teste e inicialização).
Veja por que você não deve concentrar tudo no blueprint acme-devtools: os blueprints de repositório são executados depois que todos os repositórios são clonados, mas suas etapas são executadas no diretório desse repositório, e suas entradas de knowledge são carregadas somente quando o Devin está trabalhando nesse repositório. Se acme-devtools instalasse tudo, uma sessão em acme-portal não veria nenhum dos comandos de lint e teste do portal, e uma única etapa com falha em acme-devtools deixaria os outros quatro repositórios com aparência de saudáveis, mas inutilizáveis.

O blueprint da organização

Organization-wide setup
Três pontos a observar:
  1. initialize versus maintenance. Docker, runtime e hostnames são configurações únicas do sistema, então pertencem a initialize. As credenciais do registro devem ser atualizadas a cada build periódica, então pertencem a maintenance. A própria CLI acme está deliberadamente ausente aqui. Ela fica dentro de acme-devtools, e as etapas da organização são executadas antes de qualquer repositório ser clonado, então sua instalação vem do blueprint desse próprio repositório (mostrado abaixo). Essa instalação é executada durante a build e persiste no snapshot, de onde todos os outros repositórios podem usá-la.
  2. post-build é a grande vantagem das configurações com vários repositórios. Ele é executado depois que todos os repositórios foram clonados e configurados, então é o único lugar em que você pode validar se a stack inteira sobe corretamente. Um código de saída diferente de zero faz a build falhar, então você descobre uma stack quebrada no momento da build, e não no meio da sessão. Veja post-build.
  3. Os segredos pertencem à organização, não a cada repositório. Um único ACME_REGISTRY_TOKEN na aba Segredos do blueprint da organização atende ao bundle install e ao npm install de todos os repositórios.
Atenção à ordem: initialize e maintenance da organização são executados antes de os repositórios serem clonados (consulte a ordem da build). Tudo o que depende de código-fonte já clonado — como uma CLI que fica dentro de um dos seus repositórios — deve ficar no blueprint desse repositório ou em post-build, não em maintenance da organização. Mantenha isso no nível da organização apenas se for possível instalar a partir de um artefato já publicado, como um tarball, um pacote ou uma imagem de contêiner.

Os blueprints de repositório

Cada blueprint de repositório é pequeno, porque tudo o que é compartilhado já existe:
acme-devtools (repository blueprint)
acme-portal (repository blueprint)
acme-web, acme-sso e acme-events seguem o mesmo padrão: uma etapa maintenance para as próprias dependências e entradas de knowledge para os próprios comandos de lint, teste e inicialização.
Coloque acme-devtools primeiro na lista de repositórios. Os blueprints dos repositórios são executados na ordem exibida em Configurações, então o repositório que fornece a CLI compartilhada deve ser configurado antes dos repositórios que a utilizam.
O Knowledge é específico de cada repositório. Com cinco repositórios configurados, uma sessão trabalhando em acme-portal vê as entradas de Knowledge do portal, além do Knowledge da organização e do Enterprise — ela não vê as entradas de acme-web. É por isso que cada repositório merece seu próprio blueprint, mesmo quando sua seção maintenance tem apenas uma linha.
Como a CLI acme já sabe executar tudo, a parte mais valiosa desses blueprints é a seção knowledge: ela ensina o Devin qual comando de CLI usar. Se você tiver uma busca de documentação interna, aponte para ela.

Se, em vez disso, seus serviços estiverem em um monorepo

A ideia é a mesma, um nível abaixo: use workspaces para dar a cada pacote sua própria configuração e seu próprio conhecimento, ambos com escopo definido, dentro de um único repositório, em vez de um blueprint por repositório.

Etapa 3: várias organizações — o blueprint Enterprise

A ACME agora tem 400 engenheiros. Platform, Payments e Data têm, cada uma, sua própria organização no Devin, com repositórios separados, membros separados e snapshots separados. Uma equipe de segurança tem requisitos que se aplicam a todas elas:
  • Todo o tráfego passa por um proxy corporativo, com uma autoridade certificadora interna.
  • Todos os pacotes vêm do Artifactory, nunca de registros públicos.
  • Todo ambiente deve ter instaladas as ferramentas da empresa de varredura de dependências e segredos.
  • Python é 3.12 e Node.js é 20 em toda a empresa, sem exceções.
Nada disso pertence a um blueprint da organização, porque teria de ser copiado para todas as organizações e começaria a divergir assim que uma equipe se esquecesse de atualizá-lo. É para isso que serve o blueprint Enterprise: um ambiente base que é aplicado primeiro, no build de cada organização, em toda a empresa.
Devin's base environment (enterprise blueprint)
ARTIFACTORY_TOKEN é um segredo Enterprise, definido uma única vez em Configurações > ambiente base do Devin > Segredos e disponível em todas as builds e sessões de todas as organizações. O certificado é um arquivo anexado, exposto à build como $FILE_ACME_CA_CERT.

Do que cada nível é responsável agora

O blueprint da organização Payments da Etapa 2 continua funcionando sem alterações. Ele simplesmente não precisa mais instalar Python nem configurar registros, porque o nível Enterprise já fez isso. O blueprint da organização Data instala Spark e um JDK, que Payments nunca vê. Os blueprints de repositório permanecem inalterados.

Operando

  • Fazer upgrade do Python da 3.12 para a 3.13 exige editar uma única linha mais um rebuild em todo o Enterprise, que se propaga para todas as organizações.
  • Quando uma equipe precisa de uma credencial diferente — por exemplo, se a organização Data tem seu próprio realm no Artifactory — essa equipe define um segredo da organização com o mesmo nome, e ele faz override do segredo do Enterprise.
  • Para fazer esse rollout gradualmente entre as organizações, consulte Migrando seu Enterprise.

Decidindo onde algo deve ficar

Percorra a lista. O primeiro “sim” é a resposta:
1

Todas as organizações da empresa precisam disso?

Enterprise blueprint. Certificados, proxies, registros internos, runtimes obrigatórios, ferramentas de segurança e segredos válidos para toda a empresa.
2

Dois ou mais repositórios nesta organização precisam disso?

Blueprint da organização. Docker, CLIs de desenvolvimento compartilhadas, hostnames locais, orquestração de serviços entre repositórios e credenciais de registro. Valide a stack resultante em post-build.
3

Só este repositório precisa disso?

Blueprint de repositório. Instalação de dependências, migrações e as entradas de Knowledge para seus comandos de lint, teste e inicialização.
4

Isso é um fato, e não um comando para executar?

knowledge, no nível ao qual se aplica. Ele nunca é executado; é carregado no contexto do Devin.
Erros comuns que isso evita:
  • Colocar tudo no blueprint de um único repositório. Os outros repositórios não recebem entradas de Knowledge, e uma etapa com falha faz toda a configuração parecer comprometida.
  • Duplicar ferramentas compartilhadas em cada repositório. Quando dois repositórios instalam versões diferentes da mesma ferramenta global, a última a ser executada prevalece. Em vez disso, coloque a ferramenta no blueprint da organização.
  • Pular a verificação entre repositórios. Quando seus repositórios só funcionam em conjunto, post-build é o único lugar que comprova isso — antes de uma sessão começar, e não durante ela.