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

# Buone pratiche

> Buone pratiche enterprise per organizzare i blueprint, gestire i segreti, monitorare le build, il pinning e la migrazione su larga scala.

Utilizzare Devin in un contesto enterprise significa gestire ambienti per decine di organizzazioni e centinaia di repository. Questa pagina illustra i pattern che funzionano bene su larga scala e gli errori da evitare.

<div id="organizing-blueprints-across-tiers">
  ## Organizzare i blueprint tra i vari livelli
</div>

La domanda più comune che gli amministratori Enterprise si pongono è: "Dove dovrebbe andare questa configurazione?"

La risposta è semplice: **inseriscila nel blueprint Enterprise per impostazione predefinita.** Il blueprint Enterprise è il posto giusto per tutto ciò che si applica (o potrebbe applicarsi) a tutte le organizzazioni. Questo include runtime dei linguaggi, strumenti di sicurezza, certificati aziendali, CLI interni, configurazione del proxy e autenticazione condivisa al registry. Va benissimo installare qui più linguaggi e strumenti, anche se non tutte le org li usano tutti.

| Livello del blueprint | Quando usarlo                                             | Esempi                                                                                                                                                   |
| --------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enterprise**        | Predefinito per tutta la configurazione condivisa         | Python 3.12, Node 20, Go 1.22, Rust, scanner di sicurezza, certificati CA aziendali, CLI interni, configurazione del proxy, token condivisi del registry |
| **Organization**      | Solo quando qualcosa **non** deve applicarsi a ogni org   | Un registry privato specifico di un team, strumenti limitati a determinati team, configurazione di linting specifica per org                             |
| **Repository**        | Configurazione per repo eseguita nella directory del repo | `npm install`, `uv sync`, elementi di Knowledge specifici del progetto, file `.envrc` a livello di repo                                                  |

**L'unico motivo per usare un blueprint org invece del blueprint Enterprise** è quando non vuoi che qualcosa venga applicato a ogni organizzazione. Ad esempio, se un team usa un registry npm privato a cui gli altri team non dovrebbero avere accesso, quella configurazione del registry appartiene al blueprint org di quel team, non al blueprint Enterprise.

Se qualcosa si applica a tutte le org, va in Enterprise. Se è specifico per repo, va nel blueprint del repo. Il livello org esiste solo per le eccezioni intermedie.

<Warning>
  Non inserire comandi specifici per repo (come `npm install`) nel blueprint Enterprise o org. Questi livelli vengono eseguiti nella directory home, non nella directory del repo, quindi i comandi specifici per repo non andranno a buon fine oppure
  installeranno i file nel posto sbagliato.
</Warning>

<div id="use-knowledge-items-at-the-right-tier">
  ### Usa gli elementi di Knowledge nel livello giusto
</div>

Gli elementi di Knowledge sono cumulativi tra i vari livelli. Devin li vede tutti. Sfrutta questa struttura per organizzare le indicazioni:

* **Knowledge Enterprise**: Standard di codifica validi per tutta l'azienda, requisiti per la revisione della sicurezza, collegamenti alla documentazione interna.
* **Knowledge dell'org**: Convenzioni del team, pattern di utilizzo delle librerie condivise, procedure di distribuzione specifiche del team.
* **Knowledge della repo**: Comandi di lint, test e build per lo specifico progetto.

<div id="secrets-management-at-scale">
  ## Gestione dei segreti su larga scala
</div>

I segreti seguono la stessa gerarchia di livelli dei blueprint; quelli più specifici hanno la precedenza.

<div id="where-to-define-secrets">
  ### Dove definire i segreti
</div>

| Ambito del segreto | Da usare per                            | Esempi                                                                                                            |
| ------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Enterprise**     | Credenziali condivise tra tutte le orgs | Token del registry interno, autenticazione del proxy corporate, API key condivise per i servizi interni           |
| **Organizzazione** | Credenziali specifiche del team         | Chiavi di distribuzione del team, token API per i servizi del team, autenticazione al registry specifica del team |
| **Repository**     | Credenziali specifiche per repo         | API key per progetto, service account specifici del progetto                                                      |

**Inserisci i segreti al livello più alto applicabile.** Se ogni org deve accedere al registry npm interno, definisci il token una sola volta come segreto Enterprise. Non duplicarlo in 50 configurazioni di org.

<div id="secret-hygiene">
  ### Buone pratiche per i segreti
</div>

* **Non inserire mai segreti nei file YAML.** Usa sempre l'interfaccia di gestione dei segreti. I segreti nei file YAML finiscono nei log, negli artefatti di build e negli audit trail.
* **Ruota regolarmente i segreti.** Quando ruoti un segreto nell'interfaccia utente, il nuovo valore viene applicato dalla build successiva. Non sono necessarie modifiche al blueprint.
* **Usa nomi descrittivi.** `INTERNAL_NPM_TOKEN` è meglio di `TOKEN_1`. Gli altri amministratori (e il te stesso del futuro) devono capire a cosa serve ogni segreto.
* **Verifica l'utilizzo dei segreti.** Controlla periodicamente quali segreti esistono e se sono ancora necessari. Rimuovi quelli inutilizzati per ridurre la superficie di attacco.

<Info>
  Se un segreto dell'org e un segreto Enterprise hanno lo stesso nome, prevale il segreto dell'org. Lo stesso vale per i segreti del repo che sovrascrivono quelli dell'org. Usalo in modo intenzionale. Per esempio, un'org potrebbe sovrascrivere il
  token del registry Enterprise con un token specifico del team con autorizzazioni diverse.
</Info>

<div id="build-health-monitoring">
  ## Monitoraggio dell'integrità delle build
</div>

Su scala aziendale, gli errori di build sono inevitabili. L'importante è individuarli tempestivamente e risolverli rapidamente.

<div id="establish-a-review-cadence">
  ### Stabilisci una cadenza di controllo
</div>

Verifica settimanalmente lo stato delle build in tutte le organizzazioni. Cerca:

* **Build fallite**: Errori critici nei blueprint Enterprise o delle org che bloccano tutte le repo.
* **Build parziali**: Alcune repo non riescono. Spesso è segno di un problema di dipendenze o di un blueprint obsoleto.
* **Build non aggiornate**: Org la cui build più recente è insolitamente vecchia, il che può indicare una coda di build bloccata.

<div id="respond-to-enterprise-blueprint-failures">
  ### Gestire gli errori del blueprint Enterprise
</div>

Se una modifica al blueprint Enterprise causa errori diffusi:

1. **Valuta la portata dell'impatto.** Verifica quante orgs sono interessate nella pagina Rollout.
2. **Ripristina il blueprint Enterprise** all'ultima versione sicuramente funzionante. Salva immediatamente. Questo attiva nuove build in tutte le orgs interessate.
3. **Indaga in isolamento.** Testa le tue modifiche su una singola org pilota prima di ridistribuirle.

Non lasciare un blueprint Enterprise non funzionante mentre esegui il debug. Ogni minuto in cui resta non funzionante, le orgs continuano a ricevere build non riuscite.

<div id="partial-builds-are-a-signal">
  ### Le build parziali sono un segnale
</div>

Una build parziale significa che alcune repo in un'org sono state completate con successo, mentre altre no. Di solito è causata da:

* Un problema di dipendenze specifico per repo (lock file danneggiato, package rimosso)
* Una libreria di sistema mancante necessaria solo a un progetto
* Un blueprint obsoleto che non è stato aggiornato per riflettere le modifiche nella repo

Le build parziali producono comunque snapshot utilizzabili per le repo che sono state completate con successo. Ma è importante indagare sui problemi. Se ignorati, tendono ad accumularsi.

<div id="when-to-pin-builds">
  ## Quando bloccare le build
</div>

Il blocco delle build congela l'ambiente di un'org a uno snapshot specifico. Usalo con attenzione.

<div id="good-reasons-to-pin">
  ### Buoni motivi per bloccare
</div>

* **Release critica in corso.** Hai bisogno di un ambiente stabile e affidabile per le prossime 48 ore, mentre distribuisci una release.
* **Debug in corso.** Stai analizzando un problema di build e non vuoi che gli aggiornamenti automatici cambino il contesto mentre lavori.
* **Rollback.** Una nuova build ha introdotto una regressione e devi ripristinare immediatamente la versione precedente mentre correggi il blueprint.

<div id="bad-reasons-to-pin">
  ### Motivi sbagliati per bloccare
</div>

* **Per evitare di risolvere il problema.** Se una build non funziona, correggi il blueprint. Applicare un blocco nasconde il problema e, dato che i blocchi non scadono automaticamente, un blocco dimenticato può lasciarti usare un ambiente obsoleto a tempo indeterminato.
* **"Per ogni evenienza."** Gli aggiornamenti automatici mantengono aggiornate le dipendenze e fanno emergere i problemi in anticipo. Disattivarli senza un motivo specifico non fa che rimandare i problemi.

<Warning>
  Puoi applicare un blocco solo a build create da meno di **7 giorni**. Una volta applicato, il blocco resta attivo finché non viene rimosso manualmente. Non scade. Un blocco dimenticato significa che il tuo team continua a usare uno
  snapshot sempre più obsoleto.
</Warning>

<div id="migrating-your-enterprise">
  ## Eseguire la migrazione della tua Enterprise
</div>

Per il playbook consigliato per una migrazione graduale (dal testing iniziale al rollout completo), consulta [Eseguire la migrazione della tua Enterprise](/it/enterprise/environment-management/rollout#recommended-migration-playbook).

<div id="common-architectural-patterns">
  ## Modelli architetturali comuni
</div>

Strutture aziendali diverse richiedono strategie di progettazione differenti.

<div id="monorepo-organizations">
  ### Organizzazioni monorepo
</div>

**Configurazione**: Un'org con un unico grande repo che contiene più progetti.

**Approccio**: Il **blueprint Enterprise** gestisce tutti gli strumenti condivisi (runtime, strumenti CLI globali, registri). Inserisci la configurazione specifica del progetto (`npm install` nella directory del frontend, `uv sync` nella directory del backend) nel **blueprint del repo**. Il blueprint org è necessario solo se questa org ha strumenti o configurazioni che non devono essere applicati ad altre org.

Usa un singolo blueprint con subshells per gestire più progetti:

```yaml theme={null}
# Blueprint del repo per un 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">
  ### Organizzazioni multi-repo
</div>

**Configurazione**: Un'org con più repo correlati (ad es. un team che gestisce microservizi).

**Approccio**: Inserisci il tooling condiviso e la configurazione del registry nel **blueprint dell'org**. Ogni repo ha il proprio blueprint con solo `maintenance` e `knowledge`. In questo modo eviti di duplicare i comandi di configurazione tra i repo.

<div id="shared-infrastructure-org">
  ### org di infrastruttura condivisa
</div>

**Configurazione**: Un'org di piattaforma o DevOps che fornisce servizi condivisi utilizzati da altri team.

**Approccio**: Il **blueprint Enterprise** definisce la base comune. Il blueprint dell'org di infrastruttura condivisa installa gli strumenti specifici della piattaforma (Terraform, kubectl, CLI cloud) necessari alle sue repo. Le altre org non ricevono questi strumenti. Ricevono solo ciò che è incluso nel blueprint Enterprise, oltre alla configurazione della propria org.

<div id="isolated-project-orgs">
  ### org di progetto isolate
</div>

**Configurazione**: Team indipendenti senza strumenti condivisi oltre agli elementi di base.

**Approccio**: Il **blueprint enterprise** continua a gestire la base comune: tutti i runtime standard dei linguaggi, gli strumenti di sicurezza e l'infrastruttura aziendale. Ogni org usa il proprio blueprint solo per strumenti o configurazioni realmente specifici di quel team e che non dovrebbero essere condivisi con altri. I blueprint del repo gestiscono la configurazione per progetto.

<Info>
  Nel dubbio, inseriscilo nel blueprint enterprise. Se un'org ha un motivo specifico per escludere qualcosa (versioni degli strumenti in conflitto, accesso limitato), può sovrascriverlo a livello di org. È
  più semplice avere una base enterprise completa che duplicare la configurazione in molti blueprint di org.
</Info>