Vai al contenuto principale

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

Avvia una sessione Devin

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

Rivedi e approva

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

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.
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:
ConcettoCos’èAnalogia
BlueprintUna configurazione YAML che descrive cosa installare e come configurare l’ambiente di DevinDockerfile
BuildIl processo che esegue il blueprint, clona le repo e produce uno snapshotdocker build
SnapshotUn’immagine immutabile e avviabile dell’ambiente da cui vengono avviate le sessioniDocker 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:
SezioneScopoQuando viene eseguita
initializeInstalla strumenti, runtime e pacchetti di sistemaSolo durante le build. I risultati vengono salvati nello snapshot.
maintenanceInstalla/aggiorna le dipendenze del progetto, scrive le configurazioni delle credenzialiDurante le build. Viene mostrato all’agente all’inizio della sessione (non eseguito automaticamente).
knowledgeInformazioni di riferimento per Devin (comandi di lint, test e build)Non viene eseguito. Caricato nel contesto di Devin all’inizio della sessione.
cloneEsegue 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:
LivelloDove configurareCosa inserire qui
OrganizzazioneSettings > Environment > Blueprints > Configurazione a livello di orgStrumenti condivisi tra tutte le repo: runtime dei linguaggi, gestori di pacchetti, autenticazione Docker
RepositorySettings > 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:
  1. Viene scaricata la versione più recente del codice per le repo pertinenti.
  2. 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.
  3. 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

AttivazioneDescrizione
Salvataggio di un blueprintCreazione, aggiornamento o eliminazione di un blueprint
Aggiunta o rimozione di un repositoryQualsiasi modifica all’elenco dei repository
Aggiunta di un segreto del repositoryPer rendere disponibili i nuovi segreti è necessaria una rebuild
Attivazione manualeFacendo clic su Build snapshot nella UI
Aggiornamento periodicoAutomatico, circa ogni 24 ore
Suggerimento di DevinDevin 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

StatusMeaning
SuccessTutti i passaggi sono stati completati. Lo snapshot è pronto.
PartialAlcuni 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.
FailedErrore critico (configurazione dell’org o di Enterprise non riuscita). Lo snapshot non è utilizzabile.
CancelledSostituita 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:
StatoSignificato
ConfiguratoHa un blueprint con inizializzazione/manutenzione/Knowledge. È completamente configurato nello snapshot.
InclusoClonato nello snapshot, ma senza blueprint personalizzato. Devin può accedere al codice.
DisponibileConnesso 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

  1. Verifica i log di build per individuare l’errore
  2. Aggiorna il blueprint pertinente
  3. Salva (una nuova build si attiva automaticamente)
  4. Monitora i log della nuova build
  5. 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.