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

# Scenari: la crescita con ACME Corp

> Come la configurazione dei blueprint si evolve da un singolo repository a un'applicazione con più repository e dipendenze condivise, fino a un ambiente Enterprise con più organizzazioni.

I blueprint hanno tre livelli — repository, organizzazione ed Enterprise — e la domanda più comune è *a quale livello deve appartenere questo elemento?*

Questa pagina risponde a questa domanda seguendo un'azienda fittizia, **ACME Corp**, attraverso tre fasi di crescita. Ogni fase introduce esattamente un nuovo problema, e ogni problema viene risolto dal livello successivo. Vai direttamente alla fase che assomiglia di più alla tua azienda.

| Fase                                                                                              | Come si presenta ACME                                                                    | Cosa configurano                                                      |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [1. Un repository](#stage-1-one-repository)                                                       | Una singola applicazione Rails, un team                                                  | Un blueprint del repository                                           |
| [2. Più repository, dipendenze condivise](#stage-2-several-repositories-with-shared-dependencies) | Cinque repository, una CLI di sviluppo condivisa, servizi che dipendono l'uno dall'altro | Un blueprint dell'organizzazione più un blueprint per ogni repository |
| [3. Più organizzazioni](#stage-3-multiple-organizations-the-enterprise-blueprint)                 | Diversi team, ciascuno con la propria organizzazione, più un team di sicurezza           | Un blueprint Enterprise più blueprint per organizzazione              |

<Info>
  La regola pratica, in breve: **i blueprint del repository installano le dipendenze del progetto, i blueprint dell'organizzazione installano tutto ciò che è condiviso da più di un repository e i blueprint Enterprise installano tutto ciò che ogni organizzazione deve avere.** I livelli sono additivi e vengono eseguiti dall'alto verso il basso: Enterprise → organizzazione → clonazione dei repository → repository.
</Info>

***

<div id="stage-1-one-repository">
  ## Fase 1: un repository
</div>

ACME ha un prodotto: `acme-web`, un'applicazione Rails con Postgres e Redis. Due ingegneri, un repository. Non c'è ancora nulla da condividere, quindi **tutto va nel blueprint del repository**.

Aggiungono il repository in **Settings > Environment > Blueprints > Add**, ne aprono l'editor e scrivono:

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

Questa è l'intera configurazione. La salvano, si avvia una build e ogni sessione parte con Ruby installato, Postgres in esecuzione, le gem installate e il database migrato.

**Perché non c'è ancora un blueprint dell'organizzazione?** Un blueprint dell'organizzazione che serve una sola repo aggiunge solo un livello di indirezione. Aspetta finché una seconda repo non avrà bisogno della stessa cosa.

<Tip>
  ACME non l'ha scritto a mano. Ha chiesto a Devin *"configura il tuo ambiente per questa repo"*, ha esaminato la scheda di suggerimento e ha fatto clic su **Approve**. Vedi [Per iniziare](/it/onboard-devin/environment/blueprints#getting-started).
</Tip>

***

<div id="stage-2-several-repositories-with-shared-dependencies">
  ## Fase 2: più repository con dipendenze condivise
</div>

Due anni dopo, ACME ha cinque repository:

| Repository      | Cos'è                                                                                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `acme-devtools` | Una CLI (`acme`) che avvia container, collega tra loro i servizi ed espone hostname locali (`acme.local`, `portal.acme.local`). Gestisce anche la ricerca nella documentazione interna (`acme docs:search`). |
| `acme-web`      | L'applicazione principale. La maggior parte delle funzionalità viene sviluppata qui.                                                                                                                         |
| `acme-portal`   | Portale per i clienti. Chiama `acme-web`.                                                                                                                                                                    |
| `acme-sso`      | Servizio di autenticazione. Entrambe le applicazioni dipendono da esso.                                                                                                                                      |
| `acme-events`   | Consumer di eventi.                                                                                                                                                                                          |

Questo è il caso interessante, perché i repository **non sono indipendenti**: in `acme-portal` non si riesce a fare nulla di utile se `acme-devtools` non è installato e `acme-sso` non è in esecuzione. Sorgono due domande.

<div id="one-blueprint-per-application-or-just-one-for-the-development-cli">
  ### "Un blueprint per ogni applicazione, o ne basta uno per la CLI di sviluppo?"
</div>

**Entrambi — svolgono funzioni diverse.** Devin crea *un unico snapshot* che contiene *tutti* i repository configurati, quindi non si tratta di una scelta tra le due opzioni:

* Aggiungi **tutti e cinque i repository** all'ambiente, in modo che vengano tutti clonati nello snapshot.
* Inserisci la **configurazione condivisa tra più repository una sola volta** nel **blueprint dell'organizzazione**: runtime dei linguaggi, Docker, hostname locali e credenziali per il registry interno.
* Assegna a ogni repository il proprio **blueprint del repository** per le dipendenze specifiche e le relative voci di `knowledge` (comandi di lint, test e avvio).

Ecco perché non dovresti accentrare tutto nel blueprint `acme-devtools`: i blueprint del repository vengono eseguiti dopo che tutti i repository sono stati clonati, ma i relativi passaggi vengono eseguiti **nella directory di quel repository**, e le relative voci di `knowledge` vengono caricate solo quando Devin sta lavorando in quel repository. Se `acme-devtools` installasse tutto, una sessione che lavora in `acme-portal` non vedrebbe nessuno dei comandi di lint e test del portale, e un singolo passaggio non riuscito di `acme-devtools` lascerebbe gli altri quattro repository apparentemente integri ma inutilizzabili.

<div id="the-organization-blueprint">
  ### Il blueprint dell'organizzazione
</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
```

Tre cose da notare:

1. **`initialize` rispetto a `maintenance`.** Docker, i runtime e gli hostname fanno parte della configurazione di sistema una tantum, quindi vanno in `initialize`. Le credenziali del registry, invece, devono essere aggiornate a ogni build periodica, quindi vanno in `maintenance`.

   La CLI `acme` è volutamente assente qui. Si trova all'interno di `acme-devtools` e i passaggi a livello di organizzazione vengono eseguiti **prima che qualsiasi repository venga clonato**, quindi viene installata dal blueprint di quel repository (mostrato sotto). L'installazione avviene durante la build e rimane nello snapshot, da cui poi ogni altro repository può usarla.
2. **`post-build` è il vero vantaggio delle configurazioni con più repository.** Viene eseguito dopo che *tutti* i repository sono stati clonati e configurati, quindi è l'unico punto in cui puoi verificare che l'intero stack si avvii correttamente nel suo insieme. Un codice di uscita diverso da zero fa fallire la build, quindi scopri che lo stack non funziona già in fase di build invece che a metà sessione. Vedi [`post-build`](/it/onboard-devin/environment/blueprint-reference#post-build).
3. **I Secrets appartengono all'organizzazione**, non a ciascun repository. Un solo `ACME_REGISTRY_TOKEN` nella scheda **Secrets** del blueprint dell'organizzazione serve per `bundle install` e `npm install` di tutti i repository.

<Warning>
  **Attenzione all'ordine di esecuzione:** `initialize` e `maintenance` dell'organizzazione vengono entrambi eseguiti **prima** che i repository vengano clonati (vedi [ordine di build](/it/onboard-devin/environment/blueprints#how-builds-work)). Tutto ciò che richiede codice sorgente già estratto — come una CLI che si trova *all'interno* di uno dei tuoi repository — deve stare nel blueprint di quel repository o in `post-build`, non in `maintenance` dell'organizzazione. Tienilo nel livello dell'organizzazione solo se puoi installarlo da un artefatto distribuito, come un tarball, un package o un'immagine container.
</Warning>

<div id="the-repository-blueprints">
  ### I blueprint di repository
</div>

Ogni blueprint del repository rimane piccolo, perché tutto ciò che è condiviso esiste già:

```yaml acme-devtools (repository blueprint) theme={null}
initialize: |
  ./bin/install            # aggiunge `acme` al PATH per l'intero snapshot

maintenance: |
  acme docs:index          # aggiorna l'indice della documentazione interna a ogni 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` hanno la stessa struttura: un passaggio `maintenance` per le rispettive dipendenze e voci di `Knowledge` per i rispettivi comandi di lint, test e avvio.

<Tip>
  **Metti `acme-devtools` per primo** nell'elenco dei repository. I blueprint dei repository vengono eseguiti nell'ordine mostrato in Settings, quindi il repository che fornisce la CLI condivisa deve essere configurato prima dei repository che la richiamano.
</Tip>

<Info>
  **Knowledge è specifico per repository.** Con cinque repository configurati, una session che lavora in `acme-portal` vede le voci di Knowledge del portal, oltre a Knowledge dell'organizzazione e dell'Enterprise, ma non vede le voci di `acme-web`. Ecco perché ogni repository dovrebbe avere il proprio blueprint, anche quando la sezione `maintenance` è composta da una sola riga.
</Info>

<Tip>
  Poiché la CLI `acme` sa già come eseguire tutto, la parte più utile di questi blueprint è la sezione **`knowledge`**: insegna a Devin quale comando CLI usare. Se disponibile, indirizzala alla ricerca della tua documentazione interna.
</Tip>

<div id="if-your-services-live-in-a-monorepo-instead">
  ### Se invece i tuoi servizi si trovano in un monorepo
</div>

L'idea è la stessa, un livello più in basso: usa i [workspace](/it/onboard-devin/environment/workspaces) per dare a ogni package una configurazione e una Knowledge specifiche all'interno di un singolo repository, anziché un blueprint per ogni repository.

***

<div id="stage-3-multiple-organizations-the-enterprise-blueprint">
  ## Fase 3: più organizzazioni — il blueprint enterprise
</div>

ACME ora ha 400 ingegneri. Platform, Payments e Data hanno ciascuna una propria **organizzazione** in Devin, con repository separati, membri separati e snapshot separate. Un team di sicurezza ha requisiti che si applicano a tutte:

* Tutto il traffico passa attraverso un proxy aziendale, con un'autorità di certificazione interna.
* Tutti i package provengono da Artifactory, mai da registry pubblici.
* Ogni ambiente deve avere installati gli strumenti aziendali per la scansione delle dipendenze e dei secret.
* Python è 3.12 e Node.js è 20 in tutta l'azienda, senza eccezioni.

Nulla di tutto questo dovrebbe stare in un blueprint dell'organizzazione, perché andrebbe **copiato in ogni organizzazione** e inizierebbe a divergere non appena un team si dimenticasse di aggiornarlo. È proprio a questo che serve il **blueprint enterprise**: un ambiente di base che viene eseguito per primo nella build di ogni organizzazione, in tutta l'azienda.

```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` è un **segreto Enterprise**, definito una sola volta in **Settings > ambiente di base di Devin > Secrets** e disponibile in ogni build e in ogni session di ogni organizzazione. Il certificato è un file allegato, messo a disposizione della build come `$FILE_ACME_CA_CERT`.

<div id="what-each-tier-owns-now">
  ### Cosa gestisce ora ciascun livello
</div>

| Livello            | Responsabile                                       | Esempio ACME                                                                             |
| ------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Enterprise**     | Amministratori della sicurezza e della piattaforma | Autorità di certificazione, proxy, Artifactory, Python 3.12, scanner, un token condiviso |
| **Organizzazione** | Gli amministratori di ciascun team                 | Payments: Docker, la CLI `acme` e gli hostname del team. Data: Spark e JDK 17.           |
| **Repository**     | Chiunque sia responsabile del repository           | `bundle install`, `npm install` e informazioni su lint, test e avvio                     |

Il blueprint dell'organizzazione Payments della Fase 2 continua a funzionare **senza modifiche**. Semplicemente, non deve più installare Python né configurare i registry, perché il livello Enterprise lo ha già fatto. Il blueprint dell'organizzazione Data installa Spark e un JDK, che Payments non usa mai. I blueprint del repository restano invariati.

<div id="operating-it">
  ### Gestione operativa
</div>

* **L'aggiornamento di Python dalla versione 3.12 alla 3.13** richiede una modifica di una sola riga più un [rebuild esteso a tutta l'Enterprise](/it/enterprise/environment-management/overview#enterprise-wide-rebuilds), che si applica in cascata a tutte le organizzazioni.
* **Quando un team ha bisogno di una credenziale diversa** — ad esempio, se l'organizzazione Data ha un proprio realm di Artifactory — quel team definisce un segreto dell'organizzazione con lo stesso nome, che **override** il segreto Enterprise.
* **Per eseguire gradualmente questo rollout** tra le organizzazioni, consulta [Migrare la tua Enterprise](/it/enterprise/environment-management/rollout).

***

<div id="deciding-where-something-goes">
  ## Decidere dove va ogni elemento
</div>

Procedi lungo l'elenco. Il primo "sì" è la risposta:

<Steps>
  <Step title="Ne ha bisogno ogni organizzazione dell'azienda?">
    → **blueprint enterprise.** Certificati, proxy, registry interni, runtime obbligatori, strumenti di sicurezza e secret validi per tutta l'azienda.
  </Step>

  <Step title="Ne hanno bisogno due o più repository in questa organizzazione?">
    → **blueprint dell'organizzazione.** Docker, CLI di sviluppo condivise, hostnames locali, orchestrazione dei servizi tra repository e credenziali del registry. Convalida lo stack risultante in `post-build`.
  </Step>

  <Step title="Ne ha bisogno solo questo repository?">
    → **blueprint del repository.** Installazione delle dipendenze, migrazioni e voci di `knowledge` per i relativi comandi di lint, test e avvio.
  </Step>

  <Step title="Si tratta di un'informazione anziché di un comando da eseguire?">
    → **`knowledge`**, al livello a cui si applica. Non viene mai eseguito; viene caricato nel contesto di Devin.
  </Step>
</Steps>

Errori comuni che questo approccio evita:

* **Mettere tutto nel blueprint di un solo repository.** Gli altri repository non ricevono voci di `knowledge` e un singolo passaggio che fallisce fa sembrare problematico l'intero setup.
* **Duplicare gli strumenti condivisi in ogni repository.** Quando due repository installano versioni diverse dello stesso strumento globale, prevale l'ultima esecuzione. Inserisci invece lo strumento nel blueprint dell'organizzazione.
* **Saltare la verifica tra repository.** Quando i repository funzionano solo insieme, `post-build` è l'unico punto in cui lo si può verificare, prima che inizi una sessione anziché durante.

<div id="related-pages">
  ## Pagine correlate
</div>

* [Configurazione dichiarativa](/it/onboard-devin/environment/blueprints) — ordine di build, snapshot e risoluzione dei problemi
* [Riferimento del blueprint](/it/onboard-devin/environment/blueprint-reference) — tutti i campi, inclusi `post-build` e `clone`
* [Libreria di template](/it/onboard-devin/environment/templates) — blueprint da copiare e incollare per ogni linguaggio e registry
* [Workspace e monorepo](/it/onboard-devin/environment/workspaces) — l'equivalente monorepo di Stage 2
* [Panoramica dell'ambiente Enterprise](/it/enterprise/environment-management/overview) — Stage 3 in tutti i dettagli