> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Boas práticas

> Boas práticas do Enterprise para organizar blueprints, gerenciar segredos, monitorar builds, fixar versões e migrar em escala.

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.

<div id="organizing-blueprints-across-tiers">
  ## Organizando blueprints entre níveis
</div>

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 blueprint | Quando usar                                            | Exemplos                                                                                                                                                           |
| ------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Enterprise**     | Padrão para toda configuração compartilhada            | Python 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ção**    | Somente quando algo **não** deve se aplicar a toda org | Um registro privado específico de uma equipe, ferramentas restritas a determinadas equipes, configuração de linting específica da org                              |
| **repositório**    | Configuração por repo executada no diretório do repo   | `npm 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.

<Warning>
  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.
</Warning>

<div id="use-knowledge-items-at-the-right-tier">
  ### Use os itens do Knowledge no nível certo
</div>

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.

<div id="secrets-management-at-scale">
  ## Gerenciamento de segredos em grande escala
</div>

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

<div id="where-to-define-secrets">
  ### Onde definir segredos
</div>

| Escopo do segredo | Use para                                    | Exemplos                                                                                                              |
| ----------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Enterprise**    | Credenciais compartilhadas por todas as org | Tokens de registro interno, autenticação de proxy corporativo, chaves de API compartilhadas para serviços internos    |
| **Organização**   | Credenciais específicas da equipe           | Chaves de implantação da equipe, tokens de API para serviços da equipe, autenticação de registro específica da equipe |
| **Repositório**   | Credenciais específicas do repo             | Chaves 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.

<div id="secret-hygiene">
  ### Higiene de segredos
</div>

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

<Info>
  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.
</Info>

<div id="build-health-monitoring">
  ## Monitoramento da saúde dos builds
</div>

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

<div id="establish-a-review-cadence">
  ### Estabeleça uma cadência de revisão
</div>

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.

<div id="respond-to-enterprise-blueprint-failures">
  ### Responda a falhas no blueprint do Enterprise
</div>

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.

<div id="partial-builds-are-a-signal">
  ### Builds parciais são um sinal
</div>

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.

<div id="when-to-pin-builds">
  ## Quando fixar builds
</div>

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

<div id="good-reasons-to-pin">
  ### Bons motivos para fixar builds
</div>

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

<div id="bad-reasons-to-pin">
  ### Maus motivos para fixar
</div>

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

<Warning>
  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.
</Warning>

<div id="migrating-your-enterprise">
  ## Migração da sua Enterprise
</div>

Para o playbook recomendado de migração em fases (dos testes iniciais à implementação completa), consulte [Migração da sua Enterprise](/pt-BR/enterprise/environment-management/rollout#recommended-migration-playbook).

<div id="common-architectural-patterns">
  ## Padrões comuns de arquitetura
</div>

Diferentes estruturas Enterprise exigem diferentes estratégias de arquitetura.

<div id="monorepo-organizations">
  ### Organizações monorepo
</div>

**Configuração**: Uma org com um único repositório grande que contém vários projetos.

**Abordagem**: O **blueprint do 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 org.

Use um único blueprint com subshells para lidar com vários projetos:

```yaml theme={null}
# Blueprint do 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 .
```

<div id="multi-repo-organizations">
  ### Organizações com vários repositórios
</div>

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

<div id="shared-infrastructure-org">
  ### org de infraestrutura compartilhada
</div>

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

<div id="isolated-project-orgs">
  ### Orgs de projeto isoladas
</div>

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

<Info>
  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.
</Info>