Blueprint supportati da Git

Panoramica

I blueprint supportati da Git ti consentono di archiviare la configurazione del tuo ambiente direttamente nel repository come file .devin/blueprint.yaml. Sincronizzi il file con Devin tramite l’API o la UI, quindi attivi una build dello snapshot per applicare le modifiche. In questo modo hai lo stesso flusso di lavoro che usi per il codice dell’applicazione: modifichi nell’IDE, apri una pull request, ottieni una review, fai il merge e poi sincronizzi + avvii la build tramite un passaggio CI o dalla UI.

Approccio	Dove si trova il blueprint	Come lo modifichi	Come vengono applicate le modifiche
Supportato da Git	`.devin/blueprint.yaml` nella tua repo	Modifica nel tuo IDE, fai il merge di una PR	Chiama l’API di sincronizzazione (o fai clic su Sync nella UI), quindi attiva una build — oppure abilita sincronizzazione e build a ogni commit sul branch predefinito
Database	interfaccia Settings di Devin	Modifica nel Browser	Salvato immediatamente al clic

Come Devin sceglie la modalità quando aggiungi un repository

La modalità basata su Git è quella predefinita ogni volta che è presente un file blueprint nella repo. Quando aggiungi un repository al tuo ambiente, Devin controlla il branch predefinito per .devin/blueprint.yaml:

Se il file esiste, Devin recupera il blueprint da Git (modalità basata su Git) e registra il commit SHA da cui è stato sincronizzato.
Se il file non è presente (o il rilevamento non riesce), Devin crea un blueprint vuoto che gestisci nell’interfaccia Settings (modalità database).

Puoi passare un repository da una modalità all’altra in qualsiasi momento: vedi Passare tra la modalità Git e la modalità database.

I blueprint basati su Git usano lo stesso formato YAML dell’editor della UI. Consulta il riferimento del blueprint per la specifica completa dei campi.

Guida introduttiva

Crea il file blueprint

Aggiungi un file .devin/blueprint.yaml nella directory principale del tuo repository:

my-repo/
  .devin/
    blueprint.yaml
  src/
  package.json
  ...

Il file utilizza lo stesso formato YAML dell’editor della UI:

initialize:
  - name: Install Node.js 22
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "22"

maintenance:
  - name: Install dependencies
    run: npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test

Esegui il push al branch predefinito

Esegui il commit e il push di .devin/blueprint.yaml nel branch predefinito del tuo repository (in genere main o master). Se il repository è già connesso all’ambiente di Devin, devi avviare una sincronizzazione (tramite l’API o il pulsante Sync dell’UI) affinché Devin rilevi il file, a meno che il blueprint non sia già in modalità basata su Git e il repository non abbia l’opzione Run on every commit to default branch abilitata. Se il blueprint è in modalità Database, passa a Git per importare il file. Se stai aggiungendo la repo per la prima volta, il processo di discovery iniziale legge il blueprint da Git.

Verifica nella UI

Vai a Settings > Environment > Blueprints e fai clic sul repository. L’Editor mostra il contenuto del blueprint proveniente da Git e l’indicatore della sorgente mostra il nome del provider (ad es. “GitHub”) con lo SHA del commit sincronizzato.

Come funziona la sincronizzazione

La sincronizzazione consiste nel recuperare .devin/blueprint.yaml dal commit HEAD del branch predefinito della repo e nell’aggiornare le versioni del blueprint archiviate da Devin. Per impostazione predefinita, la sincronizzazione non avviene automaticamente al push. La sincronizzazione viene eseguita in questi casi:

Sincronizzazione tramite API — Chiama l’endpoint di sincronizzazione (beta) (vedi Sincronizzazione tramite l’API di seguito). È l’approccio consigliato per le pipeline CI/CD.
Sincronizzazione tramite UI — Fai clic sul pulsante Sync nell’editor dei blueprint. Se il contenuto è cambiato, questo attiva anche una build dello snapshot.
Quando aggiungi una repo all’ambiente — Se .devin/blueprint.yaml esiste nel branch predefinito, il blueprint viene recuperato automaticamente da Git durante la fase iniziale di discovery.
A ogni commit sul branch predefinito (attivazione facoltativa) — Per le repository con Run on every commit to default branch abilitato, ogni push sul branch predefinito sincronizza il blueprint e attiva una build. Vedi Sincronizza e crea la build a ogni commit sul branch predefinito.

La sincronizzazione è idempotente: se il contenuto del file non è cambiato dall’ultima sincronizzazione, non viene creata alcuna nuova versione.

Sync e build a ogni commit sul branch predefinito

Per i repository GitHub.com, puoi attivare sync e build automatici anziché chiamare l’API dalla CI o fare clic su Sync:

Vai su Settings > Environment > Blueprints e fai clic sul repository.
Apri la tab Advanced.
Attiva Run on every commit to default branch.

Con questa impostazione attiva, ogni push sul branch predefinito sincronizza il blueprint supportato da Git e mette in coda una build dello snapshot per ciascuna piattaforma. Se arriva un commit più recente mentre la build di un commit precedente è ancora in coda, quest’ultima viene annullata in modo che venga compilato solo il commit più recente; le build già avviate vengono invece portate a termine. Se il blueprint del repository è in modalità database, la build utilizza il blueprint salvato in Devin anziché il file proveniente dal commit. Attiva Report status checks for each commit per mostrare il risultato di ogni build come check run di GitHub sul commit.

La tab Advanced compare solo per i repository GitHub.com e solo quando questa opzione è disponibile per la tua organizzazione. Per gli altri Git provider, o quando l’impostazione è disattivata, usa la sync via API o il button Sync.

Sync vs. build

Sync e build sono operazioni distinte:

Sync recupera l’ultima versione di .devin/blueprint.yaml da Git e salva una nuova versione del blueprint.
Build crea una nuova immagine snapshot a partire dalle versioni correnti del blueprint.

Il pulsante di sincronizzazione nella UI esegue entrambi i passaggi in un’unica azione. L’API li separa, così hai il pieno controllo: esegui prima la sync, poi avvia una build.

Sincronizzazione tramite l’API

Gli endpoint dei blueprint e delle build fanno parte dell’API stabile /v3/. Gli endpoint di sincronizzazione sono ancora in beta e sono disponibili in /v3beta1/; i relativi percorsi e formati di request/response potrebbero cambiare prima della promozione a /v3/.

Se Run on every commit to default branch non è disponibile o è disabilitata per il tuo repository, il modo consigliato per mantenere sincronizzati i blueprint è chiamare l’API dopo aver eseguito il merge delle modifiche in .devin/blueprint.yaml. In genere, questa operazione viene eseguita da una pipeline CI/CD (ad es. come passaggio post-merge di GitHub Actions).

Flusso completo

Passaggio 1: sincronizza il blueprint

Scarica la versione più recente di .devin/blueprint.yaml dal branch predefinito:

curl -X POST https://api.devin.ai/v3beta1/organizations/{org_id}/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'

Risposta:

{"repo_name": "owner/repo"}

Il campo repo_name accetta owner/repo per GitHub oppure un URL completo del provider per altri host (ad es. https://gitlab.com/org/repo).

Passaggio 2: Avvia una Build dello Snapshot

Dopo la sincronizzazione, avvia una Build dello Snapshot per applicare il nuovo blueprint:

curl -X POST https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Risposta:

{
  "build_id": "sbj-abc123",
  "status": "pending",
  "trigger": "manual",
  "triggered_by_user_id": "user-abc123",
  "pinned": false,
  "started_at": null,
  "completed_at": null,
  "created_at": 1718000000,
  "updated_at": 1718000000
}

Passaggio 3: Monitora lo stato della build (facoltativo)

Se vuoi attendere il completamento della build nel CI:

curl https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds/{build_id} \
  -H "Authorization: Bearer $DEVIN_API_TOKEN"

Il campo status passa attraverso i seguenti stati: pending → running → succeeded oppure failed (o cancelled). Una build parziale viene segnalata come succeeded dall’API perché lo snapshot è utilizzabile.

Sincronizzazione a livello di Enterprise

Per le Enterprise in cui più organizzazioni condividono lo stesso repository, esiste un endpoint a livello di Enterprise che sincronizza tutte le org collegate alla repo:

curl -X POST https://api.devin.ai/v3beta1/enterprise/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'

La risposta include il numero di org sincronizzate:

{"repo_name": "owner/repo", "org_count": 3}

Esempio: flusso di lavoro GitHub Actions

Automatizza la sincronizzazione e la build a ogni push sul branch predefinito che modifica il file blueprint:

# .github/workflows/sync-blueprint.yml
name: Sync Devin Blueprint

on:
  push:
    branches: [main]
    paths:
      - '.devin/blueprint.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync blueprint
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3beta1/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/sync" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"repo_name": "${{ github.repository }}"}'

      - name: Trigger build
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/builds" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{}'

Ti serve un utente di servizio o un token di accesso personale con autorizzazioni di scrittura per l’ambiente. Salva il token come DEVIN_API_TOKEN e l’ID della tua org come DEVIN_ORG_ID nei secret del repository.

Modificare i blueprint supportati da Git

Quando un blueprint è supportato da Git, nell’interfaccia utente l’editor è in sola lettura e non consente il salvataggio diretto. Hai invece due opzioni per apportare modifiche:

Crea una PR dall’editor

Apri l’editor dei blueprint in Settings > Environment > Blueprints
Modifica il file YAML nell’editor
Fai clic su Create PR
Devin apre una pull request nel tuo repository che aggiorna .devin/blueprint.yaml
Rivedi, approva ed esegui il merge della PR
La sincronizzazione successiva rileva la modifica e attiva una build

Questa opzione è utile per modifiche rapide senza uscire dalla UI di Devin.

Modifica direttamente nel tuo repository

Modifica .devin/blueprint.yaml nel tuo IDE o sul tuo provider Git
Esegui il commit e il push sul branch predefinito (oppure apri una PR ed esegui il merge)
Avvia una sincronizzazione tramite l’API o fai clic su Sync nella UI (non necessario se Run on every commit to default branch è abilitato)

Questo è il flusso di lavoro standard per i team che gestiscono l’Infrastructure as Code. Abbinalo a un passaggio della CI per automatizzare la sincronizzazione (vedi Sincronizzazione tramite l’API), oppure abilita la sincronizzazione automatica sui commit del branch predefinito.

Suggerimenti di Devin

Quando Devin propone una modifica al blueprint durante una sessione (ad es., dopo aver analizzato il tuo progetto), il suggerimento viene applicato aprendo una pull request (PR) per .devin/blueprint.yaml, anziché salvarlo direttamente nel database. La PR viene quindi esaminata e integrata proprio come qualsiasi altra modifica al codice.

Monorepo e workspace

Per i monorepo con più package, puoi usare la direttiva includes per definire blueprint separati per ciascun workspace. Ogni workspace ha il proprio file .devin/blueprint.yaml nella relativa sottodirectory.

Blueprint radice con include

Il blueprint radice .devin/blueprint.yaml dichiara quali workspace hanno blueprint propri:

# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

Blueprint dei workspace

Ogni workspace incluso ha il proprio .devin/blueprint.yaml:

# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

knowledge:
  - name: lint
    contents: pnpm lint
  - name: test
    contents: pnpm test

# my-repo/packages/backend/.devin/blueprint.yaml
maintenance: |
  pip install -r requirements.txt

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

Regole per gli include

Ogni voce in includes è il percorso di una sottodirectory (ad es. packages/frontend). Devin cerca .devin/blueprint.yaml all’interno di quella directory.
Puoi anche usare il percorso completo: packages/frontend/.devin/blueprint.yaml.
Solo il blueprint radice può contenere includes. Gli include annidati (ovvero un blueprint incluso che a sua volta dichiara includes) non sono consentiti.
Ogni percorso di workspace può comparire una sola volta in includes.
Se un file incluso non è presente nel repository, quel workspace viene considerato rimosso e il relativo blueprint viene eliminato.

Passaggio tra la modalità Git e quella database

Passa a Git

Se hai un blueprint esistente gestito nel database e vuoi passare a Git:

Crea .devin/blueprint.yaml nel repository con il contenuto desiderato
Esegui il push nel branch predefinito
Nell’editor del blueprint, fai clic sul menu a discesa della sorgente e seleziona il provider Git desiderato (ad es. “GitHub”)
Devin sincronizza il file da Git e passa alla modalità basata su Git

Passa al database

Se vuoi smettere di usare la modalità basata su Git e gestire il blueprint nella UI:

Nel blueprint editor, fai clic sul menu a discesa della sorgente e seleziona Database
Il contenuto attuale viene mantenuto, ma i futuri push a .devin/blueprint.yaml non aggiorneranno più il blueprint
Ora puoi modificare e salvare direttamente nella UI

Se passi il blueprint radice alla modalità database, anche tutti i blueprint dei workspace di quella repo passeranno alla modalità database, poiché la sincronizzazione avviene a livello di repo.

Workspace scollegati

Puoi scollegare i singoli blueprint dei workspace da Git mantenendo la radice in modalità basata su Git. Un workspace scollegato è modificabile nella UI e viene escluso dalla sincronizzazione. Questo è utile quando un workspace richiede un override temporaneo senza influire sul resto del repo. Per ricollegare un workspace scollegato, imposta di nuovo la sua sorgente su Git dal menu a discesa della sorgente.

Cronologia delle versioni

Ogni sincronizzazione crea una nuova versione nella cronologia del blueprint, contrassegnata con:

Sorgente: git_sync per le versioni create dalla sincronizzazione, manual per le versioni create nell’interfaccia utente
Commit SHA: il commit del branch predefinito su cui è stata eseguita la sincronizzazione (collegamento al commit nel tuo provider Git)

Puoi visualizzare la cronologia completa delle versioni e i diff nella scheda Cronologia delle versioni del blueprint editor.

YAML multidocumento

Come nell’editor della UI, .devin/blueprint.yaml supporta YAML multidocumento tramite il separatore ---. Questo ti consente di definire configurazioni specifiche della piattaforma in un unico file:

# Configurazione Linux (default)
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync
---
runs-on: windows

initialize: |
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

maintenance: |
  uv sync

Consulta Supporto per Windows per maggiori dettagli sui blueprint multipiattaforma.

Risoluzione dei problemi

Il Blueprint non si sincronizza

Il file si trova nel percorso corretto? Deve essere .devin/blueprint.yaml nella directory radice del repository (o <workspace>/.devin/blueprint.yaml per i workspace inclusi).
Hai avviato una sincronizzazione? Per impostazione predefinita, la sincronizzazione non avviene automaticamente al push. Chiama l’endpoint API di sincronizzazione oppure fai clic sul pulsante Sync nella UI. Se ti aspetti che i push si sincronizzino automaticamente, verifica che Run on every commit to default branch sia abilitato nella tab Advanced del repository e che tu abbia effettuato il push sul branch predefinito.
Il repository è nell’ambiente di Devin? Il repo deve essere aggiunto in Settings > Environment > Blueprints perché la sincronizzazione venga eseguita.
La modalità basata su Git è abilitata? Il blueprint deve essere in modalità basata su Git (non in modalità database) perché la sincronizzazione lo aggiorni.

Errori di YAML non valido

Se .devin/blueprint.yaml contiene YAML non valido o non è conforme allo schema del blueprint, la sincronizzazione non va a buon fine e restituisce un errore. Correggi il file nel branch predefinito e sincronizza di nuovo. L’editor dei blueprint nella UI convalida lo schema e mostra gli errori prima che tu apra una PR, aiutandoti a individuare i problemi prima che arrivino nel branch predefinito.

Blueprint mostra “Database” dopo il push

Se hai eseguito il push di un .devin/blueprint.yaml ma l’Editor continua a mostrare “Database” come sorgente, è possibile che il blueprint non sia ancora passato alla modalità basata su Git. Usa il menu a discesa della sorgente per passare al tuo provider Git, attivando così la sincronizzazione iniziale.

​Panoramica

​Come Devin sceglie la modalità quando aggiungi un repository

​Guida introduttiva

​ Crea il file blueprint

​ Esegui il push al branch predefinito

​ Verifica nella UI

​Come funziona la sincronizzazione

​Sync e build a ogni commit sul branch predefinito

​Sync vs. build

​Sincronizzazione tramite l’API

​Flusso completo

​Passaggio 1: sincronizza il blueprint

​Passaggio 2: Avvia una Build dello Snapshot

​Passaggio 3: Monitora lo stato della build (facoltativo)

​Sincronizzazione a livello di Enterprise

​Esempio: flusso di lavoro GitHub Actions

​Modificare i blueprint supportati da Git

​Crea una PR dall’editor

​Modifica direttamente nel tuo repository

​Suggerimenti di Devin

​Monorepo e workspace

​Blueprint radice con include

​Blueprint dei workspace

​Regole per gli include

​Passaggio tra la modalità Git e quella database

​Passa a Git

​Passa al database

​Workspace scollegati

​Cronologia delle versioni

​YAML multidocumento

​Risoluzione dei problemi

​Il Blueprint non si sincronizza

​Errori di YAML non valido

​Blueprint mostra “Database” dopo il push

Panoramica

Come Devin sceglie la modalità quando aggiungi un repository

Guida introduttiva

Crea il file blueprint

Esegui il push al branch predefinito

Verifica nella UI

Come funziona la sincronizzazione

Sync e build a ogni commit sul branch predefinito

Sync vs. build

Sincronizzazione tramite l’API

Flusso completo

Passaggio 1: sincronizza il blueprint

Passaggio 2: Avvia una Build dello Snapshot

Passaggio 3: Monitora lo stato della build (facoltativo)

Sincronizzazione a livello di Enterprise

Esempio: flusso di lavoro GitHub Actions

Modificare i blueprint supportati da Git

Crea una PR dall’editor

Modifica direttamente nel tuo repository

Suggerimenti di Devin

Monorepo e workspace

Blueprint radice con include

Blueprint dei workspace

Regole per gli include

Passaggio tra la modalità Git e quella database

Passa a Git

Passa al database

Workspace scollegati

Cronologia delle versioni

YAML multidocumento

Risoluzione dei problemi

Il Blueprint non si sincronizza

Errori di YAML non valido

Blueprint mostra “Database” dopo il push