Pular para o conteúdo principal
Usar o Devin em escala corporativa significa gerenciar ambientes para dezenas de organizações e centenas de repositórios. Esta página aborda as práticas que funcionam bem em escala e os erros a evitar.

​
Organizando blueprints entre níveis

A pergunta mais comum que os admins do Enterprise fazem é: “Onde essa configuração deve ficar?” A resposta é simples: coloque-a no blueprint do Enterprise por padrão. O blueprint do Enterprise é o lugar certo para tudo o que se aplica (ou poderia se aplicar) a todas as organizações. Isso inclui runtimes de linguagem, ferramentas de segurança, certificados corporativos, CLIs internas, configuração de proxy e autenticação em registros compartilhados. Não há problema em instalar várias linguagens e ferramentas aqui, mesmo que nem toda org use todas elas.
Nível do blueprintQuando usarExemplos
EnterprisePadrão para toda configuração compartilhadaPython 3.12, Node 20, Go 1.22, Rust, scanners de segurança, certificados de CA corporativa, CLIs internas, configuração de proxy, tokens de registro compartilhado
organizaçãoSomente quando algo não deve se aplicar a toda orgUm registro privado específico de uma equipe, ferramentas restritas a determinadas equipes, configuração de linting específica da org
repositórioConfiguração por repo executada no diretório do reponpm install, uv sync, itens do Knowledge específicos do projeto, arquivos .envrc no nível do repo
O único motivo para usar um blueprint de org em vez do blueprint do Enterprise é quando você especificamente não quer que algo seja aplicado a todas as organizações. Por exemplo, se uma equipe usa um registro npm privado ao qual outras equipes não devem ter acesso, essa configuração de registro pertence ao blueprint da org dessa equipe, e não ao blueprint do Enterprise. Se algo se aplica a todas as org, vai no Enterprise. Se for específico do repo, vai no blueprint do repo. O nível de org existe apenas para as exceções entre esses dois casos.
Não coloque comandos específicos do repo (como npm install) no blueprint do Enterprise ou da org. Esses níveis são executados no diretório home, não no diretório do repo, então comandos específicos do repo vão falhar ou instalar no lugar errado.

​
Use os itens do Knowledge no nível certo

Os itens do Knowledge são cumulativos entre os níveis. O Devin vê todos eles. Use isso para organizar as orientações em camadas:
  • Knowledge da Enterprise: Padrões de código da empresa, requisitos de revisão de segurança, links para a documentação interna.
  • Knowledge da org: Convenções da equipe, padrões de uso de bibliotecas compartilhadas, procedimentos de deployment específicos da equipe.
  • Knowledge do repo: Comandos de lint, teste e build para o projeto específico.

​
Gerenciamento de segredos em grande escala

Os segredos seguem a mesma hierarquia de níveis dos blueprints, e os segredos mais específicos têm prioridade.

​
Onde definir segredos

Escopo do segredoUse paraExemplos
EnterpriseCredenciais compartilhadas por todas as orgTokens de registro interno, autenticação de proxy corporativo, chaves de API compartilhadas para serviços internos
OrganizaçãoCredenciais específicas da equipeChaves de implantação da equipe, tokens de API para serviços da equipe, autenticação de registro específica da equipe
RepositórioCredenciais específicas do repoChaves de API por projeto, contas de serviço específicas do projeto
Coloque os segredos no nível mais alto aplicável. Se todas as org precisarem de acesso ao registro interno do npm, defina o token como um segredo Enterprise uma única vez. Não o duplique em 50 configurações de org.

​
Higiene de segredos

  • Nunca coloque segredos em YAML. Sempre use a interface de gerenciamento de segredos. Segredos em YAML acabam em logs, artefatos de build e trilhas de auditoria.
  • Rotacione segredos regularmente. Quando você rotaciona um segredo na interface, o novo valor passa a valer no próximo build. Nenhuma alteração no blueprint é necessária.
  • Use nomes descritivos. INTERNAL_NPM_TOKEN é melhor do que TOKEN_1. Outros administradores (e você no futuro) precisam entender para que serve cada segredo.
  • Audite o uso de segredos. Revise periodicamente quais segredos existem e se eles ainda são necessários. Remova segredos não utilizados para reduzir sua superfície de ataque.
Se um segredo da org e um segredo do Enterprise tiverem o mesmo nome, o segredo da org prevalece. O mesmo vale para segredos de repositório substituindo segredos da org. Use isso intencionalmente. Por exemplo, uma org pode substituir o token de registro do Enterprise por um token específico da equipe com permissões diferentes.

​
Monitoramento da saúde dos builds

Em escala Enterprise, falhas de build são inevitáveis. O importante é identificá-las cedo e resolvê-las rapidamente.

​
Estabeleça uma cadência de revisão

Verifique semanalmente a saúde dos builds em todas as organizações. Procure por:
  • Builds com falha: Falhas críticas em blueprints da Enterprise ou da org que bloqueiam todos os repos.
  • Builds parciais: Alguns repos com falha. Muitas vezes, isso indica um problema de dependência ou um blueprint desatualizado.
  • Builds desatualizados: Orgs cujo build mais recente está excepcionalmente antigo, o que pode indicar uma fila de builds travada.

​
Responda a falhas no blueprint do Enterprise

Se uma alteração no blueprint do Enterprise causar falhas generalizadas:
  1. Avalie o alcance do impacto. Verifique quantas orgs foram afetadas na página Rollout.
  2. Reverta o blueprint do Enterprise para o último blueprint estável conhecido. Salve imediatamente. Isso aciona rebuilds em todas as orgs afetadas.
  3. Investigue de forma isolada. Teste suas alterações em uma única org piloto antes de implantá-las novamente.
Não deixe um blueprint do Enterprise com falha enquanto depura o problema. A cada minuto em que ele permanece com falha, as orgs recebem builds com falha.

​
Builds parciais são um sinal

Um build parcial significa que alguns repositórios em uma org foram concluídos com sucesso, enquanto outros falharam. Isso geralmente é causado por:
  • Um problema de dependência específico do repositório (arquivo de lock corrompido, pacote removido)
  • Uma biblioteca de sistema ausente, necessária apenas para um dos projetos
  • Um blueprint desatualizado, que não foi atualizado para acompanhar as mudanças no repositório
Builds parciais ainda produzem snapshots utilizáveis para os repositórios que foram concluídos com sucesso. Mas investigue as falhas. Elas tendem a se acumular se forem ignoradas.

​
Quando fixar builds

Fixar builds congela o ambiente de uma org em um snapshot específico. Use isso com critério.

​
Bons motivos para fixar builds

  • Lançamento crítico em andamento. Você precisa de um ambiente estável e confiável pelas próximas 48 horas enquanto lança uma nova versão.
  • Depuração ativa. Você está investigando um problema de build e não quer que atualizações automáticas alterem o ambiente durante a investigação.
  • Rollback. Um novo build causou uma regressão, e você precisa reverter imediatamente enquanto corrige o blueprint.

​
Maus motivos para fixar

  • Evitar uma correção. Se um build estiver com problema, corrija o blueprint. Fixar mascara o problema e, como pins não expiram automaticamente, um pin esquecido pode fazer com que você continue usando um ambiente desatualizado por tempo indeterminado.
  • “Só por precaução.” As atualizações automáticas mantêm as dependências atualizadas e detectam problemas cedo. Desativá-las sem nenhum motivo específico só adia os problemas.
Você só pode fixar builds com menos de 7 dias. Depois de fixado, o pin permanece ativo até ser removido manualmente. Ele não expira. Um pin esquecido significa que sua equipe continuará usando um snapshot cada vez mais desatualizado.

​
Migração da sua Enterprise

Para o playbook recomendado de migração em fases (dos testes iniciais à implementação completa), consulte Migração da sua Enterprise.

​
Padrões comuns de arquitetura

Diferentes estruturas Enterprise exigem diferentes estratégias de arquitetura.

​
Organizações monorepo

Configuração: Uma org com um único repositório grande que contém vários projetos. Abordagem: O blueprint Enterprise cuida de todas as ferramentas compartilhadas (runtimes, ferramentas globais de CLI, registros). Coloque a configuração específica de cada projeto (npm install no diretório do frontend, uv sync no diretório do backend) no blueprint do repo. O blueprint da org só é necessário se esta org tiver ferramentas ou configurações que não devam se aplicar a outras orgs. 
# Blueprint de repo para um monorepo
maintenance:
  - name: "Frontend dependencies"
    run: (cd frontend && npm install)

  - name: "Backend dependencies"
    run: (cd backend && uv sync)

knowledge:
  - name: lint
    contents: |
      Frontend: cd frontend && npm run lint
      Backend: cd backend && uv run ruff check .

​
Organizações com vários repositórios

Configuração: Uma org com vários repositórios relacionados (por exemplo, uma equipe de microsserviços). Abordagem: Coloque as ferramentas compartilhadas e a configuração do registro no blueprint da org. Cada repositório tem seu próprio blueprint com apenas maintenance e knowledge. Isso evita duplicar comandos de configuração entre os repositórios.

​
org de infraestrutura compartilhada

Configuração: Uma org de plataforma ou de DevOps que fornece serviços compartilhados usados por outras equipes. Abordagem: O blueprint Enterprise cobre a base comum. O blueprint da org de infraestrutura compartilhada instala as ferramentas específicas da plataforma (Terraform, kubectl e CLIs de nuvem) de que seus repos precisam. As outras orgs não recebem essas ferramentas. Elas recebem apenas o que está no blueprint Enterprise, além da configuração da própria org.

​
Orgs de projeto isoladas

Configuração: Equipes independentes, sem ferramentas compartilhadas além do básico. Abordagem: O blueprint Enterprise continua responsável pela base comum: todos os seus runtimes de linguagem padrão, ferramentas de segurança e infraestrutura corporativa. Cada org usa seu próprio blueprint apenas para ferramentas ou configurações que sejam realmente exclusivas daquela equipe e não devam ser compartilhadas com as demais. Os blueprints de repo cuidam da configuração de cada projeto.
Em caso de dúvida, coloque no blueprint Enterprise. Se uma org tiver um motivo específico para excluir algo (versões conflitantes de ferramentas, acesso restrito), ela poderá substituí-lo no nível da org. É mais fácil ter uma base Enterprise completa do que duplicar a configuração em vários blueprints de org.