Configurazione dichiarativa

Per iniziare

Prerequisiti: Devin deve avere accesso ai tuoi repository prima che tu possa configurarne l’ambiente. Se non hai ancora configurato l’integrazione Git, consulta Prima di iniziare per i passaggi di configurazione. Gli utenti Enterprise devono anche concedere a ogni org l’accesso ai rispettivi repo in Enterprise Settings > Autorizzazioni repository.

Usi ancora la configurazione classica? Puoi passare alla configurazione dichiarativa in qualsiasi momento. Devin può gestire per te gran parte della migrazione. Consulta Migrazione alla configurazione dichiarativa .

Lascia fare a Devin (consigliato)
Configurazione manuale

Ideale per la maggior parte degli utenti. Devin analizza il tuo progetto, determina quali strumenti e dipendenze sono necessari e genera il blueprint per te. Tu devi solo rivederlo e approvarlo.

Avvia una sessione Devin

Apri una nuova sessione e chiedi a Devin di configurare il repository. Ad esempio: “Configura l’ambiente per questo repo.”

Rivedi e approva

Devin propone un blueprint. Vedrai delle schede di suggerimento nella tua timeline. Esaminale e fai clic su Approva.

Verifica

Una volta completata la build, avvia una nuova sessione. Devin si avvia dal nuovo snapshot con tutto già configurato. Prova a chiedere a Devin di eseguire i tuoi comandi di lint o di test per confermare che tutto funzioni.

Ideale quando sai esattamente di cosa ha bisogno il tuo ambiente o vuoi il pieno controllo su ogni passaggio. È più veloce se hai già pronti i tuoi comandi.

Vai alla configurazione dell'ambiente

Vai a Settings > Environment > Blueprints nella barra laterale della tua organizzazione.Se non vedi questa opzione, la tua organizzazione potrebbe essere ancora sulla configurazione classica. Consulta Migrazione alla configurazione dichiarativa per iniziare.

Aggiungi repository

Fai clic su Aggiungi nella sezione Repository. Seleziona i repository con cui vuoi che Devin lavori, quindi conferma.I repository aggiunti qui vengono clonati nell’ambiente di Devin durante ogni build. Puoi aggiungerne altri in qualsiasi momento.

Scrivi il tuo blueprint

Fai clic su un repository per aprire il relativo editor del blueprint. Ecco un semplice esempio:

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: uv run ruff check .
  - name: test
    contents: uv run pytest

Per altri linguaggi e pattern, consulta la Libreria di template.

Salva e avvia la build

Fai clic su Salva. Una build si avvia automaticamente (in genere 2–10 minuti). Monitora l’avanzamento da Settings > Environment > Snapshots in Build corrente.

Verifica

Quando la build mostra Success, avvia una nuova sessione Devin. Devin si avvia dal nuovo snapshot con tutto già configurato. Prova a chiedere a Devin di eseguire i tuoi comandi di lint o di test per verificare che l’ambiente funzioni.

Il resto di questa guida descrive in dettaglio la procedura manuale. È utile anche per comprendere che cosa ha generato Devin se hai seguito il percorso consigliato.

Come funziona

La configurazione dichiarativa si basa su tre concetti:

Concetto	Cos’è	Analogia
Blueprint	Una configurazione YAML che descrive cosa installare e come configurare l’ambiente di Devin	Dockerfile
Build	Il processo che esegue il blueprint, clona le repo e produce uno snapshot	`docker build`
Snapshot	Un’immagine immutabile e avviabile dell’ambiente da cui vengono avviate le sessioni	Docker image

I blueprint descrivono ciò che vuoi ottenere. Li scrivi e li modifichi nell’interfaccia Settings. Le build eseguono i blueprint per produrre snapshot. Le build vengono eseguite automaticamente quando salvi un blueprint e periodicamente (~ogni 24 ore) per mantenere aggiornate le dipendenze. Gli snapshot sono la base da cui si avviano le sessioni. Ogni organizzazione ha uno snapshot attivo. Ogni sessione avvia una nuova copia. Le modifiche apportate nella sessione non vengono salvate nello snapshot.

Sezioni del blueprint

Un blueprint ha tre sezioni, più un blocco clone facoltativo per i blueprint a livello di repo:

Sezione	Scopo	Quando viene eseguita
`initialize`	Installa strumenti, runtime e pacchetti di sistema	Solo durante le build. I risultati vengono salvati nello snapshot.
`maintenance`	Installa/aggiorna le dipendenze del progetto, scrive le configurazioni delle credenziali	Durante le build. Viene mostrato all’agente all’inizio della sessione (non eseguito automaticamente).
`knowledge`	Informazioni di riferimento per Devin (comandi di lint, test e build)	Non viene eseguito. Caricato nel contesto di Devin all’inizio della sessione.
`clone`	Esegue l’override dei valori predefiniti di git clone per il repository (solo a livello di repo)	Applicato durante il passaggio di clone della build.

initialize è pensato per le operazioni che devono avvenire una sola volta: runtime dei linguaggi, pacchetti di sistema, strumenti CLI globali. maintenance è pensato per l’installazione delle dipendenze che devono rimanere aggiornate. Viene eseguito durante le build e mostrato all’agente all’inizio della sessione, così può eseguirlo di nuovo se le dipendenze sono cambiate (ad es. dopo aver recuperato la versione più recente del codice). I comandi non vengono eseguiti automaticamente all’inizio della sessione, ma devono comunque essere rapidi e incrementali (usa npm install, non npm ci). knowledge contiene informazioni di riferimento e non viene eseguito. È qui che indichi a Devin i comandi corretti per lint, testing e build. Mantieni le voci leggere e focalizzate sui comandi eseguibili. clone (solo a livello di repo) esegue l’override dei valori predefiniti che Devin usa quando clona la repo nello snapshot — ad esempio, facendo il checkout di un branch non predefinito (ref), cambiando la destinazione del clone (path) o saltando sottomoduli od oggetti LFS. Ogni campo è facoltativo. Per l’elenco completo dei campi, vedi riferimento del blueprint → clone.

Knowledge qui vs la funzionalità di prodotto Knowledge: La sezione knowledge del blueprint serve per brevi riferimenti ai comandi legati all’ambiente. Per documenti di architettura, convenzioni e flussi di lavoro del team, usa invece la funzionalità Knowledge standalone.

YAML multi-documento: L’editor del blueprint supporta YAML multi-documento usando il separatore ---. Questo ti consente di organizzare blueprint complessi in sezioni logiche all’interno di un singolo editor.

Per la specifica completa dei campi (tipi di passaggio, variabili d’ambiente, segreti e file allegati), vedi il riferimento del blueprint.

Ambito dei blueprint

Puoi definire i blueprint a due livelli:

Livello	Dove configurare	Cosa inserire qui
Organizzazione	Settings > Environment > Blueprints > Configurazione a livello di org	Strumenti condivisi tra tutte le repo: runtime dei linguaggi, gestori di pacchetti, autenticazione Docker
Repository	Settings > Environment > Blueprints > [nome repo]	Configurazione specifica del progetto: `npm install`, comandi lint/test/build

I blueprint sono additivi: i blueprint delle repo si aggiungono a quello della org. Il maintenance di una repo può usare gli strumenti installati nell’initialize della org. Se solo una repo ha bisogno di uno strumento, inseriscilo nel blueprint di quella repo. Se invece serve a tutte le repo, inseriscilo nel blueprint della org.

Utenti Enterprise: Esiste un terzo livello, il blueprint Enterprise, che si applica a tutte le organizzazioni. Per maggiori dettagli, consulta Panoramica dell’ambiente Enterprise.

Build e sessioni

Lo snapshot

La tua organizzazione ha uno snapshot attivo: un’immagine VM con i tuoi strumenti, repo e dipendenze già installati. Tutte le repo configurate vengono clonate e predisposte in quell’unica immagine. Ogni sessione si avvia da una copia pulita.

Come funzionano le build

Una build crea un nuovo snapshot eseguendo i tuoi blueprint in sequenza:

1. Enterprise blueprint, if configured (runs in ~):
   a. initialize
   b. maintenance
2. Org blueprint (runs in ~):
   a. initialize
   b. maintenance
3. Clone all repositories (up to 10 concurrent).
   Each repo's blueprint may override clone defaults via the
   `clone` block (branch/tag, depth, submodules, LFS, etc.).
4. For each configured repo, in the order shown in Settings
   (runs in ~/repos/<repo-name>):
   a. initialize
   b. maintenance
5. Health check, then snapshot is saved

I layer sono additivi: i comandi specifici per repo possono usare gli strumenti installati dall’org o dal blueprint Enterprise. I livelli inferiori non possono sovrascrivere ciò che è stato configurato a un livello superiore. Le build richiedono in genere 5–15 minuti. I singoli passaggi scadono dopo 1 ora.

Come funzionano le sessioni

Ogni sessione avvia una copia pulita dello snapshot. Quando la sessione termina, tutte le modifiche vengono scartate. All’avvio della sessione:

Viene scaricata la versione più recente del codice per le repo pertinenti.
I comandi maintenance (Enterprise, org e repo) vengono resi disponibili all’agente come contesto — non vengono eseguiti automaticamente. L’agente può eseguirli di nuovo se rileva che le dipendenze sono cambiate dall’ultima build.
Le voci di knowledge di quella repo vengono caricate nel contesto di Devin.

Knowledge è per repo. Se hai configurato 5 repo, Devin vede solo le voci di Knowledge della repo su cui sta lavorando.

Cosa attiva una build

Attivazione	Descrizione
Salvataggio di un blueprint	Creazione, aggiornamento o eliminazione di un blueprint
Aggiunta o rimozione di un repository	Qualsiasi modifica all’elenco dei repository
Aggiunta di un segreto del repository	Per rendere disponibili i nuovi segreti è necessaria una rebuild
Attivazione manuale	Facendo clic su Build snapshot nella UI
Aggiornamento periodico	Automatico, circa ogni 24 ore
Suggerimento di Devin	Devin propone una modifica al blueprint durante una session

Viene eseguita una sola build alla volta. Le nuove attivazioni annullano qualsiasi build in coda e ne avviano una nuova da zero.

Stati delle build

Status	Meaning
Success	Tutti i passaggi sono stati completati. Lo snapshot è pronto.
Partial	Alcuni passaggi a livello di repo non sono andati a buon fine, ma lo snapshot è utilizzabile. Le repo completate con successo funzionano normalmente; per quelle non riuscite è necessario correggere i blueprint.
Failed	Errore critico (configurazione dell’org o di Enterprise non riuscita). Lo snapshot non è utilizzabile.
Cancelled	Sostituita da una build più recente o annullata manualmente.

Una build parziale produce comunque uno snapshot funzionante. Se una repo su cinque ha un blueprint non valido, le altre quattro sono completamente funzionali.

La build non va a buon fine? Consulta Risoluzione dei problemi delle build per una guida al debug passaggio per passaggio.

Gestione del tuo ambiente

Stati dei repository

I repository possono trovarsi in tre stati nelle impostazioni di Environment:

Stato	Significato
Configurato	Ha un blueprint con inizializzazione/manutenzione/Knowledge. È completamente configurato nello snapshot.
Incluso	Clonato nello snapshot, ma senza blueprint personalizzato. Devin può accedere al codice.
Disponibile	Connesso all’org, ma non aggiunto all’ambiente. Non clonato.

Incluso vs. configurato: un repo “incluso” viene clonato in modo che Devin possa accedere al codice, ma non ha comandi di configurazione personalizzati. Un repo “configurato” ha istruzioni esplicite di inizializzazione/manutenzione/Knowledge.

Secrets

Fai riferimento ai Secrets usando la sintassi $VARIABLE_NAME. Aggiungili nella scheda Secrets dell’editor del blueprint.

maintenance:
  - name: Configure private registry
    run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN

I segreti sono disponibili come variabili d’ambiente durante le build e le sessioni. Vengono rimossi prima che lo snapshot venga salvato, ma se un comando scrive un valore segreto in un file di configurazione durante initialize, quel valore rimane nello snapshot. Inserisci in maintenance i passaggi che scrivono le credenziali, così vengono aggiornati durante le build periodiche. Per maggiori dettagli sugli ambiti dei segreti e sul loro comportamento, consulta il riferimento del blueprint.

Repository multipli

Ogni repo ha il proprio blueprint. Durante una build, tutte le repo vengono configurate nello stesso snapshot, clonate in directory separate e con le dipendenze installate in modo indipendente. Se due repo installano versioni diverse di uno strumento globale o modificano file condivisi (come ~/.bashrc), ha la precedenza quella eseguita per ultima. Per evitare conflitti, inserisci le installazioni degli strumenti condivisi nel blueprint org-wide.

GitHub Actions

Invece di scrivere script shell per installare strumenti e runtime, puoi fare riferimento direttamente alle GitHub Actions nel tuo blueprint. Devin scarica ed esegue l’azione durante la build, proprio come i runner CI di GitHub eseguono i passaggi di un’azione.

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

Questo è particolarmente utile per le azioni di configurazione dei linguaggi come setup-python, setup-node e setup-go, che si occupano automaticamente della gestione delle versioni e della configurazione del PATH. Per dettagli sulla sintassi, esempi e limitazioni, consulta GitHub Actions nei blueprint.

Monorepo

Puoi eseguire comandi nelle sottodirectory tramite subshell oppure creare blueprint dedicati a livello di workspace per i singoli package. Devin supporta anche voci di Knowledge per package, in modo che ogni workspace abbia i propri comandi di lint, test e build. Consulta Workspace e monorepo per istruzioni di configurazione ed esempi.

Blocco e aggiornamenti automatici

Per impostazione predefinita, Devin usa lo snapshot della build riuscita più recente. Il blocco ti consente di fissare lo snapshot di una build specifica. È utile quando una nuova build introduce una regressione o quando vuoi congelare l’ambiente per un gruppo di sessioni. Per bloccare: vai a Settings > Environment > Snapshot, trova la build nella cronologia (deve essere success o partial e avere meno di 7 giorni) e fai clic su Blocca. Quando il blocco è attivo, gli aggiornamenti periodici vengono ignorati e l’interfaccia mostra Aggiornamenti automatici in pausa. Per sbloccare: fai clic su Riprendi aggiornamenti automatici. Devin passa alla build riuscita più recente.

Blueprint basati su Git

Puoi memorizzare i blueprint come file .devin/blueprint.yaml direttamente nel tuo repository. Dopo aver unito le modifiche, chiama l’API di sincronizzazione (o fai clic su Sync nella UI) per aggiornare il blueprint, quindi avvia una build. In questo modo ottieni lo stesso flusso di lavoro di revisione del codice che usi per il codice dell’applicazione, con la sincronizzazione automatizzata tramite un passaggio di CI. Consulta Git-backed blueprints per le istruzioni di configurazione e i dettagli.

Risoluzione dei problemi di build

Il passaggio Initialize non è riuscito

Cause comuni: errore di battitura in un comando shell, pacchetto non disponibile, timeout di rete, riferimento errato a GitHub Action. Soluzione: verifica i log di build per individuare l’errore esatto. Aggiorna initialize nel tuo blueprint e salva. Una nuova build viene attivata automaticamente.

Clonazione del repository non riuscita

Cause comuni: Devin non ha accesso alla repo, la repo è stata rinominata/spostata/eliminata, problema di rete temporaneo. Soluzione: Verifica l’accesso alla repo nelle impostazioni del provider Git. Rimuovi e aggiungi nuovamente la repo se è stata rinominata.

Passaggio di manutenzione non riuscito

Cause comuni: conflitto tra dipendenze, libreria di sistema mancante, spazio su disco esaurito, file di lock non aggiornato. Soluzione: Verifica i log del pacchetto o comando che ha causato l’errore. Aggiorna maintenance o initialize per installare le dipendenze mancanti, oppure correggi il file di lock nel tuo repository.

Timeout della build

Ogni passaggio ha un timeout di 1 ora. Cause comuni: la compilazione dal sorgente di dipendenze native di grandi dimensioni (utilizza binari precompilati), il download di artefatti di grandi dimensioni, comandi che restano bloccati in attesa di input (tutti i comandi devono essere non interattivi).

Perfezionare le soluzioni

Verifica i log di build per individuare l’errore
Aggiorna il blueprint pertinente
Salva (una nuova build si attiva automaticamente)
Monitora i log della nuova build
Ripeti finché la build non va a buon fine

Non è necessario attendere che una build fallita termini. Salvare una nuova configurazione annulla qualsiasi build in coda e ne avvia una nuova da zero.

Prossimi passaggi

Build differenziali

Accelera le build ricompilando solo i workspace i cui blueprint sono cambiati.

GitHub Actions nei blueprint

Usa GitHub Actions per installare linguaggi, strumenti e SDK senza dover scrivere script shell.

Workspace e monorepo

Subshell, ambiti del workspace e voci di Knowledge per repo multi-package.

Riferimento del blueprint

Riferimento completo dei campi: tipi di passaggio, variabili d’ambiente, segreti e file allegati.

Libreria di template

Blueprint da copiare e incollare per Python, Node.js, Go, Java, Ruby, Rust e pattern avanzati.

Blueprint basati su Git

Archivia i blueprint nel tuo repo come .devin/blueprint.yaml e sincronizzali tramite l’API o la UI.

Migrazione dalla configurazione classica

Guida passo passo per passare dalla procedura guidata interattiva ai blueprint dichiarativi.

Gestione degli ambienti Enterprise

Gestione degli ambienti a livello Enterprise: gerarchia a 3 livelli, segreti e configurazione tra org.

​Per iniziare

​Come funziona

​Sezioni del blueprint

​Ambito dei blueprint

​Build e sessioni

​Lo snapshot

​Come funzionano le build

​Come funzionano le sessioni

​Cosa attiva una build

​Stati delle build

​Gestione del tuo ambiente

​Stati dei repository

​Secrets

​Repository multipli

​GitHub Actions

​Monorepo

​Blocco e aggiornamenti automatici

​Blueprint basati su Git

​Risoluzione dei problemi di build

​Il passaggio Initialize non è riuscito

​Clonazione del repository non riuscita

​Passaggio di manutenzione non riuscito

​Timeout della build

​Perfezionare le soluzioni

​Prossimi passaggi

Build differenziali

GitHub Actions nei blueprint

Workspace e monorepo

Riferimento del blueprint

Libreria di template

Blueprint basati su Git

Migrazione dalla configurazione classica

Gestione degli ambienti Enterprise

Per iniziare

Come funziona

Sezioni del blueprint

Ambito dei blueprint

Build e sessioni

Lo snapshot

Come funzionano le build

Come funzionano le sessioni

Cosa attiva una build

Stati delle build

Gestione del tuo ambiente

Stati dei repository

Secrets

Repository multipli

GitHub Actions

Monorepo

Blocco e aggiornamenti automatici

Blueprint basati su Git

Risoluzione dei problemi di build

Il passaggio Initialize non è riuscito

Clonazione del repository non riuscita

Passaggio di manutenzione non riuscito

Timeout della build

Perfezionare le soluzioni

Prossimi passaggi