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

# Cenários: crescendo com a ACME Corp

> Como a configuração de blueprint evolui de um único repositório para uma aplicação com vários repositórios e dependências compartilhadas, até chegar a uma Enterprise com várias organizações.

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.

| Estágio                                                                                                       | Como é a ACME                                                                                      | O que eles configuram                                         |
| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [1. Um repositório](#stage-1-one-repository)                                                                  | Uma única aplicação Rails, uma equipe                                                              | Um blueprint de repositório                                   |
| [2. Vários repositórios, dependências compartilhadas](#stage-2-several-repositories-with-shared-dependencies) | Cinco repositórios, uma CLI de desenvolvimento compartilhada, serviços que dependem uns dos outros | Um blueprint da organização mais um blueprint por repositório |
| [3. Várias organizações](#stage-3-multiple-organizations-the-enterprise-blueprint)                            | Várias equipes, cada uma com sua própria organização, além de uma equipe de segurança              | Um blueprint Enterprise mais blueprints por organização       |

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

***

<div id="stage-1-one-repository">
  ## Etapa 1: um repositório
</div>

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:

```yaml acme-web (repository blueprint) theme={null}
initialize:
  - name: Install Ruby 3.3
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: Install Postgres and Redis
    run: |
      sudo apt-get update -qq
      sudo apt-get install -y postgresql redis-server libpq-dev
      sudo systemctl enable --now postgresql redis-server
      sudo -u postgres createuser -s "$USER"

maintenance:
  - name: Install gems and prepare the database
    run: |
      bundle install
      bin/rails db:prepare

knowledge:
  - name: lint
    contents: bundle exec rubocop
  - name: test
    contents: bundle exec rspec
  - name: startup
    contents: bin/rails server -p 3000
```

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.

<Tip>
  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](/pt-BR/onboard-devin/environment/blueprints#getting-started).
</Tip>

***

<div id="stage-2-several-repositories-with-shared-dependencies">
  ## Etapa 2: vários repositórios com dependências compartilhadas
</div>

Dois anos depois, a ACME tem cinco repositórios:

| Repositório     | O que é                                                                                                                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `acme-devtools` | Uma CLI (`acme`) que sobe contêineres, integra os serviços e disponibiliza hostnames locais (`acme.local`, `portal.acme.local`). Ela também centraliza a busca na documentação interna (`acme docs:search`). |
| `acme-web`      | A aplicação principal. A maioria dos recursos é implementada aqui.                                                                                                                                           |
| `acme-portal`   | Portal para clientes. Ele faz chamadas para `acme-web`.                                                                                                                                                      |
| `acme-sso`      | Serviço de autenticação. Ambas as aplicações dependem dele.                                                                                                                                                  |
| `acme-events`   | Consumidor de eventos.                                                                                                                                                                                       |

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.

<div id="one-blueprint-per-application-or-just-one-for-the-development-cli">
  ### "Um blueprint por aplicação ou apenas um para a CLI de desenvolvimento?"
</div>

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

<div id="the-organization-blueprint">
  ### O blueprint da organização
</div>

```yaml Organization-wide setup theme={null}
initialize:
  - name: Install Ruby 3.3
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: Install Node.js 20
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: Install Docker and Compose
    run: |
      curl -fsSL https://get.docker.com | sh
      sudo usermod -aG docker "$USER"

  - name: Local hostnames for the development CLI
    run: |
      for host in acme.local portal.acme.local sso.acme.local; do
        grep -q " $host$" /etc/hosts \
          || echo "127.0.0.1 $host" | sudo tee -a /etc/hosts > /dev/null
      done

maintenance:
  - name: Authenticate to the internal registry
    run: |
      bundle config set --global https://gems.acme.internal "$ACME_REGISTRY_TOKEN"
      npm config set //npm.acme.internal/:_authToken "$ACME_REGISTRY_TOKEN"

post-build:
  - name: Verify the stack comes up
    run: |
      acme up --detach
      acme status
      acme down
```

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`](/pt-BR/onboard-devin/environment/blueprint-reference#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.

<Warning>
  **Atenção à ordem:** `initialize` e `maintenance` da organização são executados **antes** de os repositórios serem clonados (consulte a [ordem da build](/pt-BR/onboard-devin/environment/blueprints#how-builds-work)). 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.
</Warning>

<div id="the-repository-blueprints">
  ### Os blueprints de repositório
</div>

Cada blueprint de repositório é pequeno, porque tudo o que é compartilhado já existe:

```yaml acme-devtools (repository blueprint) theme={null}
initialize: |
  ./bin/install            # puts `acme` on the PATH for the whole snapshot

maintenance: |
  acme docs:index          # refresh the internal documentation index each build

knowledge:
  - name: cli
    contents: |
      `acme` manages every local service. Common commands:
        acme up <service>     start a service and its dependencies
        acme status           list running services
        acme docs:search <q>  search internal ACME engineering documentation
      Prefer `acme docs:search` over guessing at conventions.
```

```yaml acme-portal (repository blueprint) theme={null}
maintenance: |
  npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
  - name: startup
    contents: |
      The portal needs SSO running first:
        acme up sso
        acme up portal
      Then visit https://portal.acme.local
```

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

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

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

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

<div id="if-your-services-live-in-a-monorepo-instead">
  ### Se, em vez disso, seus serviços estiverem em um monorepo
</div>

A ideia é a mesma, um nível abaixo: use [workspaces](/pt-BR/onboard-devin/environment/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.

***

<div id="stage-3-multiple-organizations-the-enterprise-blueprint">
  ## Etapa 3: várias organizações — o blueprint Enterprise
</div>

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.

```yaml Devin's base environment (enterprise blueprint) theme={null}
initialize:
  - name: Corporate certificate authority and proxy
    run: |
      sudo cp "$FILE_ACME_CA_CERT" /usr/local/share/ca-certificates/acme-ca.crt
      sudo update-ca-certificates
      cat <<'EOF' >> ~/.bashrc
      export HTTPS_PROXY=http://proxy.acme.internal:8080
      export NO_PROXY=localhost,127.0.0.1,.acme.internal
      export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/acme-ca.crt
      export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
      EOF

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

  - name: Security tooling
    run: |
      pip install bandit safety
      curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh

maintenance:
  - name: Point every package manager at Artifactory
    run: |
      pip config set global.index-url \
        "https://devin:$ARTIFACTORY_TOKEN@artifactory.acme.internal/api/pypi/pypi/simple/"
      npm config set registry https://artifactory.acme.internal/api/npm/npm/
      npm config set //artifactory.acme.internal/api/npm/npm/:_authToken "$ARTIFACTORY_TOKEN"

knowledge:
  - name: security-policy
    contents: |
      All dependencies must resolve through artifactory.acme.internal.
      Never add a public registry to a lockfile or a CI configuration.
```

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

<div id="what-each-tier-owns-now">
  ### Do que cada nível é responsável agora
</div>

| Nível            | Responsável                               | Exemplo da ACME                                                                                             |
| ---------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Enterprise**   | Administradores de segurança e plataforma | Autoridade certificadora, proxy, Artifactory, Python 3.12, ferramentas de varredura, um token compartilhado |
| **Organization** | Administradores de cada equipe            | Payments: Docker, a CLI `acme` e os nomes de host da equipe. Data: Spark e JDK 17.                          |
| **Repository**   | Quem é responsável pelo repositório       | `bundle install`, `npm install` e instruções sobre lint, testes e inicialização                             |

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.

<div id="operating-it">
  ### Operando
</div>

* **Fazer upgrade do Python da 3.12 para a 3.13** exige editar uma única linha mais um [rebuild em todo o Enterprise](/pt-BR/enterprise/environment-management/overview#enterprise-wide-rebuilds), 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](/pt-BR/enterprise/environment-management/rollout).

***

<div id="deciding-where-something-goes">
  ## Decidindo onde algo deve ficar
</div>

Percorra a lista. O primeiro "sim" é a resposta:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.

<div id="related-pages">
  ## Páginas relacionadas
</div>

* [Configuração declarativa](/pt-BR/onboard-devin/environment/blueprints) — ordem de build, snapshots e solução de problemas
* [Referência de blueprints](/pt-BR/onboard-devin/environment/blueprint-reference) — todos os campos, incluindo `post-build` e `clone`
* [Biblioteca de templates](/pt-BR/onboard-devin/environment/templates) — blueprints para copiar e colar por linguagem e registro
* [Workspaces e monorepos](/pt-BR/onboard-devin/environment/workspaces) — o equivalente em monorepo à Etapa 2
* [Visão geral do ambiente Enterprise](/pt-BR/enterprise/environment-management/overview) — Etapa 3 em todos os detalhes