Skip to main content
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.
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.

​
Fase 1: un repository

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:
acme-web (repository blueprint)
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.
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.

​
Fase 2: più repository con dipendenze condivise

Due anni dopo, ACME ha cinque repository: 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.

​
”Un blueprint per ogni applicazione, o ne basta uno per la CLI di sviluppo?”

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.

​
Il blueprint dell’organizzazione

Organization-wide setup
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.
  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.
Attenzione all’ordine di esecuzione: initialize e maintenance dell’organizzazione vengono entrambi eseguiti prima che i repository vengano clonati (vedi ordine di build). 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.

​
I blueprint di repository

Ogni blueprint del repository rimane piccolo, perché tutto ciò che è condiviso esiste già:
acme-devtools (repository blueprint)
acme-portal (repository blueprint)
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.
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.
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.
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.

​
Se invece i tuoi servizi si trovano in un monorepo

L’idea è la stessa, un livello più in basso: usa i workspace per dare a ogni package una configurazione e una Knowledge specifiche all’interno di un singolo repository, anziché un blueprint per ogni repository.

​
Fase 3: più organizzazioni — il blueprint enterprise

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.
Devin's base environment (enterprise blueprint)
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.

​
Cosa gestisce ora ciascun livello

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.

​
Gestione operativa

  • 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, 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.

​
Decidere dove va ogni elemento

Procedi lungo l’elenco. Il primo “sì” è la risposta:
1

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

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

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

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