Vai al contenuto principale
Soluzioni agli errori di build più comuni, risposte alle domande frequenti e una guida per migrare dalla configurazione interattiva legacy.
Per la configurazione generale dell’ambiente, vedi Configurazione dell’ambiente. Per i dettagli sulla sintassi, vedi il Riferimento YAML.

​
Debug degli errori di build

​
Passaggio 1: Verificare lo stato della build

Vai a Settings > Devin’s Environment > Build History. La build mostrerà uno di questi stati:
StatoCosa significaCosa fare
SuccessTutto ha funzionatoNulla — la machine image è pronta
PartialLa build principale è riuscita, ma alcuni repo non sono andati a buon fineVerificare quali repo non sono andati a buon fine; le relative sessioni potrebbero presentare problemi
FailedLa build non è riuscitaVerificare nei log quale passaggio non è riuscito
CancelledUna build più recente ha sostituito questaNormale — avvia una build più recente, se necessario
SkippedNon sono state rilevate modifiche alla configurazioneNulla — non era necessaria alcuna build

​
Passaggio 2: Leggi i log di build

I log di build sono organizzati per passaggio:
  1. Configurazione condivisa — comandi Enterprise + validi per tutta l’org
  2. Clone — clonazione del repository
  3. Configurazione della repo — comandi specifici del repository
  4. Finalize — controllo di integrità e creazione dell’immagine
Cerca il primo errore nei log. Gli errori successivi sono spesso errori a cascata causati dal primo.
Se hai usato la forma estesa con i campi name, i log mostreranno esattamente quale passaggio è fallito. Questo è uno dei principali vantaggi di assegnare un nome ai passaggi: 
# Senza nomi — difficile da debuggare
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  npm install -g pnpm

# Con nomi — facile individuare gli errori
initialize:
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh
  - name: Install pnpm
    run: npm install -g pnpm

​
Passaggio 3: Identifica il tipo di errore

​
Errori di clonazione

Sintomo: La build non riesce in fase di clonazione. Cause comuni:
  • Accesso al repository non configurato — verificare Enterprise Settings > Integrations
  • Il repo privato richiede un token di autenticazione
  • Il repository è stato rinominato o eliminato
  • Problema di connettività di rete (è necessaria una VPN o un proxy)
Soluzione: Verificare che Devin abbia accesso al repository nelle impostazioni delle integrazioni. Per i registry privati, assicurarsi che le credenziali siano configurate in Secrets.

​
Errori di installazione delle dipendenze

Sintomo: La build fallisce durante la configurazione della repo, di solito con npm install, pip install o comandi simili. Cause comuni:
  • Il registry privato dei pacchetti richiede l’autenticazione — aggiungi il token a Secrets
  • Conflitto tra versioni dei pacchetti — blocca versioni specifiche
  • Timeout di rete — verifica se è necessaria una VPN
  • URL del registry configurato in modo errato
Soluzione: Aggiungi l’autenticazione al registry nella sezione maintenance. Consulta Esempi di configurazione per i pattern dei registry privati.

​
Errori di timeout

Sintomo: La build sembra bloccarsi, poi non riesce. Cause comuni:
  • Prompt interattivo in attesa di input — aggiungi i flag -y, usa DEBIAN_FRONTEND=noninteractive
  • L’installazione di dipendenze molto grandi richiede troppo tempo
  • Il comando supera il timeout di 1 ora
Soluzione: Aggiungi flag non interattivi a tutti i comandi di installazione. Sposta le installazioni lente una tantum in initialize, così vengono eseguite solo durante le build (non in ogni sessione). 
# Errato — rimarrà in attesa di input
initialize: |
  sudo apt-get install libpq-dev

# Corretto — non interattivo
initialize: |
  sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq libpq-dev

​
Errori di autorizzazione

Sintomo: “Permission denied” nei log. Cause comuni:
  • sudo mancante durante l’installazione di pacchetti di sistema
  • Tentativo di scrivere in directory protette
  • File appartenente a un altro utente da una build precedente
Soluzione: usa sudo per le operazioni a livello di sistema (apt-get, scrittura in /etc/, ecc.). Per i gestori di pacchetti a livello utente (npm, pip, cargo), sudo di solito non è necessario.

​
Errori “comando non trovato”

Sintomo: Uno strumento installato in initialize non è disponibile in maintenance o nei passaggi successivi. Cause comuni:
  • Lo strumento viene installato in una directory non inclusa in PATH
  • Le modifiche al profilo della shell (.bashrc) non vengono ricaricate nei passaggi successivi
Soluzione: Aggiungi a PATH la directory dello strumento tramite $ENVRC: 
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC

​
Passaggio 4: Itera

Dopo aver identificato il problema:
  1. Correggi la configurazione YAML
  2. Salva — una nuova build si avvia automaticamente
  3. Verifica i log di build della nuova build
Prova prima i comandi. Prima di aggiungere un comando alla configurazione, prova a eseguirlo in una sessione di Devin per assicurarti che funzioni. È più veloce che aspettare un ciclo di build completo.

​
Riferimento rapido agli errori comuni

ErroreCausa probabileSoluzione
command not foundStrumento non installato o non presente nel PATHAggiungilo a initialize, oppure aggiungilo al PATH tramite $ENVRC
Permission deniedsudo mancanteUsa sudo apt-get install per i pacchetti di sistema
npm ERR! 404Pacchetto privato, nessuna autenticazioneAggiungi il token di autenticazione del registry in maintenance (esempi)
E: Unable to locate packageapt-get update non eseguito primaAggiungi sudo apt-get update -qq prima di apt-get install
TimeoutInstallazione lenta o prompt interattivoSpostalo in initialize; aggiungi -y e DEBIAN_FRONTEND=noninteractive
File di configurazione vuoti dopo l’avvio della sessioneCredenziali scritte in initializeSposta i passaggi relativi alle credenziali in maintenance
La build riesce ma la sessione non funzionaIl comando maintenance fallisce all’avvio della sessioneVerifica manualmente i comandi maintenance in una sessione

​
Migrazione dalla configurazione interattiva

Se al momento utilizzi la configurazione interattiva legacy (la procedura guidata passo passo), puoi passare alla configurazione dichiarativa per ottenere maggiore riproducibilità e supporto per più repo.

​
Come funziona la migrazione

La configurazione legacy e quella dichiarativa generano ciascuna la propria machine image. Le sessioni usano l’una o l’altra, mai una configurazione ibrida. Un toggle a livello di org chiamato “Use legacy machine snapshot” controlla quale immagine viene usata:
  • Toggle ATTIVO (predefinito) — tutte le sessioni usano lo snapshot legacy. Nessuna interruzione.
  • Toggle DISATTIVO — tutte le sessioni usano lo snapshot dichiarativo.
Questo significa che puoi configurare e testare la configurazione dichiarativa in parallelo, mentre tutti gli altri continuano a lavorare con lo snapshot legacy.

​
Passaggi della migrazione

1

Prepara la configurazione

Annota i comandi dell’attuale configurazione interattiva: li assocerai alle sezioni YAML:
Passaggio del wizard legacyEquivalente dichiarativo
Git pullAutomatico (integrato)
Configure secretsSecrets (invariato)
Install dependenciessezione initialize
Maintain dependenciessezione maintenance
Set up lintvoce knowledge chiamata lint
Set up testsvoce knowledge chiamata test
Run local appvoce knowledge chiamata startup
Additional notesvoce knowledge chiamata notes
2

Scrivi il tuo YAML

Vai a Settings > Devin’s Environment e seleziona il tuo repository. Associa i tuoi comandi legacy:
# Legacy "Install Dependencies" → initialize
initialize: |
  nvm use 18
  npm install -g pnpm

# Legacy "Maintain Dependencies" → maintenance
maintenance: |
  pnpm install

# Legacy "Set up lint/tests/app/notes" → knowledge
knowledge:
  - name: lint
    contents: |
      pnpm lint
  - name: test
    contents: |
      pnpm test
  - name: startup
    contents: |
      pnpm dev (port 3000)
  - name: notes
    contents: |
      Always run lint before committing.
Oppure avvia semplicemente una sessione di Devin e chiedigli di configurare il repo: Devin può generare automaticamente la configurazione per te.
3

Salva e attendi la build

Salva la configurazione. Una build si avvia automaticamente. Monitora l’avanzamento in Build History. Le build sono gratuite: non consumano ACU.
4

Testa prima del passaggio

Prima di migrare tutti, testa la configurazione dichiarativa su singole sessioni usando l’override manuale. In questo modo tu (o chi sta iterando sulla configurazione) potete usare lo snapshot dichiarativo mentre tutti gli altri restano sullo snapshot legacy.Continua a iterare sulla configurazione finché la configurazione dichiarativa non raggiunge piena parità con il tuo ambiente legacy.
5

Completa il passaggio

Quando sei sicuro, imposta su OFF “Use legacy machine snapshot” nelle impostazioni della tua org. Tutte le nuove sessioni useranno ora lo snapshot dichiarativo.
I flussi di autenticazione interattivi (ad esempio l’accesso AWS SSO dal browser o i flussi OAuth che richiedono un browser) non possono essere replicati nel formato dichiarativo. Se la tua configurazione legacy usa un’autenticazione basata su browser, dovrai convertire questi flussi in alternative headless (API key, token di service account, ecc.) prima della migrazione. Aggiungi le credenziali a Secrets e fai riferimento a esse nella sezione maintenance.

​
Migrazione Enterprise

Per le aziende con più organizzazioni:
  1. Configurate prima il file YAML a livello Enterprise — infrastruttura condivisa come VPN, certificati e impostazioni del proxy.
  2. Eseguite la migrazione di una org alla volta. Ogni org ha il proprio toggle legacy, quindi potete migrare progressivamente senza influire sugli altri team.
  3. Valutate l’uso di una org di test. Per le grandi aziende, create un’organizzazione di test dedicata per convalidare la configurazione dichiarativa prima di distribuirla nelle org di produzione.
  4. Usate Devin su larga scala. Devin può configurare le repo tramite sessioni parallele: avviate una sessione per ogni repo e Devin genererà automaticamente proposte di configurazione. Funziona bene per l’onboarding di 10–100+ repo.

​
Che cosa succede al mio vecchio snapshot?

Il tuo vecchio snapshot viene conservato. Se la nuova build dichiarativa non va a buon fine, Devin ripristina lo snapshot più recente creato correttamente (che potrebbe essere quello legacy). Puoi anche ripristinare snapshot precedenti dalla Cronologia build.

​
Differenze principali

FunzionalitàLegacy (interattivo)Dichiarativo (YAML)
RiproducibilitàCon stato persistente — gli snapshot accumulano modifica nel tempoCompletamente riproducibile da YAML
Multi-repoUna repo alla voltaPiù repo in una build con clonazione simultanea
ManutenzionePassaggi manuali “maintain dependencies”Automatica — maintenance viene eseguito all’inizio della sessione
Layer Enterprise/orgNon supportatiGerarchia a 3 livelli (Enterprise → Org → Repo)
Suggerimenti di DevinSolo nella procedura guidataDurante la sessione — Devin può suggerire aggiornamenti alla configurazione
CostoLe sessioni della procedura guidata richiedevano ACUSessioni di setup ~1–3 ACU; le build sono gratuite

​
Domande frequenti

​
Generale

Cosa succede se avvio una sessione su una repo che non è configurata? Devin continuerà a funzionare, ma dovrà ricostruire il progetto da zero ogni volta. Questo significa spendere tempo per installare le dipendenze, capire come eseguire build e test e dedurre le convenzioni del progetto. Le sessioni richiedono più tempo e costano più ACU. Configurare l’ambiente fa sì che Devin avvii ogni sessione già configurata e pronta all’uso. Quanto tempo richiede una build? In genere da 5 a 15 minuti, a seconda del numero di repo e delle dimensioni delle dipendenze. Le build vanno in timeout dopo 2 ore. Quanto costa? Le build sono gratuite e non consumano ACU. Se usi una sessione di Devin per configurare una repo (ad esempio chiedendo a Devin di generare la configurazione), quella sessione in genere costa 1–3 ACU. Una volta salvata la configurazione, tutte le build successive generate da essa sono gratuite. Posco usare sia la configurazione legacy sia quella dichiarativa? Una org usa una sola modalità alla volta, controllata dall’interruttore “Use legacy machine snapshot”. Puoi configurare in parallelo la configurazione dichiarativa mentre l’interruttore è ancora attivo (modalità legacy), quindi passare a quella dichiarativa quando sei pronto. Per i dettagli, consulta la guida alla migrazione. Posso testare la configurazione dichiarativa senza influire sugli altri utenti? Sì. Usa l’override manuale sulle singole sessioni per usare temporaneamente lo snapshot dichiarativo mentre tutti gli altri restano sullo snapshot legacy. Per le aziende, puoi anche creare un’organizzazione di test dedicata. Cosa succede se la mia build non va a buon fine? Devin usa lo snapshot riuscito più recente. Una build non riuscita non compromette le sessioni esistenti. Quando dovrei usare initialize invece di maintenance? Usa initialize per installazioni una tantum di strumenti (apt-get install, configurazione del runtime del linguaggio, strumenti CLI globali). Usa maintenance per l’installazione di dipendenze che devono restare aggiornate (npm install, pip install, uv sync). Come aggiungo variabili di ambiente? Scrivile in $ENVRC: 
initialize: |
  echo "MY_VAR=value" >> $ENVRC
Posso installare pacchetti di sistema? Sì, usa sudo apt-get install nella sezione initialize. Usa sempre DEBIAN_FRONTEND=noninteractive e il flag -y per evitare prompt interattivi. E se mi servono versioni diverse di Node per repo diversi? Usa nvm nella configurazione del repo: 
initialize: |
  nvm install 18
  nvm use 18
I flussi di autenticazione interattivi sono supportati? No. L’autenticazione basata su browser (come l’accesso tramite AWS SSO o i flussi OAuth che richiedono una finestra del browser) non può essere replicata nel formato dichiarativo. Converti questi casi in alternative headless: usa API key, token di service account o altri metodi basati su credenziali e archiviali in Secrets. Al momento non esiste alcuna soluzione alternativa per i flussi di lavoro che richiedono strettamente SSO basato su browser. Queste repo dovrebbero continuare a usare la configurazione interattiva finché non saranno disponibili alternative headless.

​
Specifico per la build

Che cosa significa “successo parziale”? La build principale (setup di Enterprise e dell’org + clonazione) è andata a buon fine, ma una o più configurazioni a livello di repo non sono riuscite. Le sessioni funzioneranno, ma nelle repo interessate le dipendenze potrebbero non essere installate correttamente. Perché la mia build è stata annullata? È stata avviata una build più recente prima che la tua build fosse completata. Viene eseguita solo la build più recente; le build meno recenti in coda vengono annullate automaticamente. Se modifico la configurazione di una repo, viene ricostruito tutto? Sì — una build crea un’unica machine image che contiene tutte le repo configurate. Qualsiasi modifica a una configurazione attiva una ricostruzione completa. Posso ripristinare una build precedente? Sì, tramite Build History nelle Environment Settings. Puoi ripristinare qualsiasi snapshot precedente andata a buon fine. Quante repo posso includere? Durante una build vengono clonate contemporaneamente fino a 10 repo. Non esiste un limite rigido al numero totale di repo, ma più repo significano build più lunghe. Devin può configurare repo su larga scala tramite sessioni parallele: avvia una sessione per repo per 10–100+ repo.

​
Specifico per Enterprise

Chi può modificare la configurazione a livello di Enterprise? Solo gli admin Enterprise. Gli admin dell’org possono modificare la configurazione a livello di org e di repo. I membri standard possono modificare la configurazione a livello di repo se hanno l’autorizzazione ManageOrgSnapshots. Consulta Configurazione dell’ambiente Enterprise per la tabella completa delle autorizzazioni. La modifica della configurazione Enterprise ricompila tutte le org? Sì. Una modifica a livello Enterprise attiva le build per ogni organizzazione dell’Enterprise. Org diverse possono avere configurazioni diverse? Sì. Ogni org ha la propria configurazione a livello di org e le proprie configurazioni a livello di repo. La configurazione Enterprise è condivisa e additiva: viene eseguita prima della configurazione di ogni org. Le configurazioni di livello inferiore possono sovrascrivere quelle di livello superiore? No. La gerarchia (Enterprise → Org → Repo) è strettamente additiva. I comandi di ciascun livello vengono eseguiti in sequenza dopo il completamento del livello precedente. I livelli inferiori non possono impedire né modificare ciò che viene configurato dai livelli superiori. La configurazione a livello Enterprise può clonare repository? No. La clonazione dei repository richiede l’accesso a livello di org. La configurazione a livello Enterprise può installare strumenti e infrastruttura condivisi, ma la clonazione dei repo deve essere configurata a livello di org o di repo.

​
Limitazioni note

  • Nessuna anteprima/sandbox di build — ogni modifica alla configurazione avvia una build completa. Prova prima i comandi in una sessione.
  • Configurazione seriale del repo — la configurazione a livello di repository viene eseguita su un repo alla volta (in ordine alfabetico). Un numero elevato di repo comporta build più lunghe.
  • Nessuna logica condizionale in YAML — il formato non supporta costrutti if/else. Se necessario, usa condizioni della shell nei comandi (ad es., [ -f package.json ] && npm install).
  • Nessuna ricerca nei log di build — i log di build devono essere scorsi manualmente. Usa passaggi denominati per individuare più facilmente gli errori.

​
Passaggi successivi