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:
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 + all’inizio di ogni sessione
knowledgeInformazioni di riferimento per Devin (comandi di lint, test e build)Non viene eseguito. Caricato nel contesto di Devin all’inizio della sessione.
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 di nuovo all’inizio della sessione dopo aver recuperato la versione più recente del codice, quindi i comandi devono 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.
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.
Per la specifica completa dei campi (tipi di passaggio, supporto per GitHub Actions, variabili d’ambiente, segreti e allegati di file), vedi il riferimento del blueprint.

​
Ambito dei blueprint

Puoi definire i blueprint a due livelli:
LivelloDove configurareCosa inserire qui
OrganizzazioneSettings > Configurazione dell’ambiente > Configurazione a livello di orgStrumenti condivisi tra tutte le repo: runtime dei linguaggi, gestori di pacchetti, autenticazione Docker
RepositorySettings > Configurazione dell’ambiente > [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)
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 cumulativi: 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. Vengono eseguiti i run di maintenance di Enterprise e a livello di org (in ~).
  2. Viene scaricata la versione più recente del codice per le repo pertinenti.
  3. Il maintenance di quella repo viene eseguito di nuovo per rilevare eventuali modifiche alle dipendenze dall’ultima build.
  4. 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 o Rebuild 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 in Settings > Secrets. 
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. Scrivi sempre le credenziali in maintenance. 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.

​
Monorepo

In un monorepo, scrivi un unico blueprint che copra tutti i sottoprogetti. Usa le subshell per eseguire comandi nelle sottodirectory: 
maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)
Le parentesi (cd ... && ...) vengono eseguite in una subshell, così la directory di lavoro si reimposta per il passaggio successivo.

​
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 Cronologia delle build snapshot, trova la build (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

I blueprint basati su Git non sono ancora supportati. Questa funzionalità sarà disponibile a breve. Potrai archiviare i blueprint nel tuo repository e fare in modo che le build si avviino automaticamente quando vengono modificati. Per ora, configura i blueprint tramite l’interfaccia utente.

​
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

Riferimento del blueprint

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

Libreria di template

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

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.