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 snapshot build 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
Database (predefinito)	interfaccia Settings di Devin	Modifica nel Browser	Salvato immediatamente al clic
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

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

Guida introduttiva

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

2. 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. Se stai aggiungendo la repo per la prima volta, il processo di discovery iniziale legge il blueprint da Git.

3. 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. La sincronizzazione non avviene automaticamente al push: devi attivarla esplicitamente:

Sincronizzazione tramite API — Chiama l’endpoint di sincronizzazione v3 (vedi Sincronizzazione tramite l’API di seguito). È l’approccio consigliato per le pipeline CI/CD.
Sincronizzazione tramite UI — Fai clic sul pulsante Sync nel blueprint editor. Se il contenuto è cambiato, questo attiva anche uno snapshot build.
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.

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

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 v3 li separa, così hai il pieno controllo: esegui prima la sync, poi avvia una build.

Sincronizzazione tramite l’API

Il modo consigliato per mantenere sincronizzati i blueprint è chiamare l’API v3 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/v3/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 snapshot

Dopo la sincronizzazione, avvia una build 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": "running",
  "trigger": "api",
  "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: running → succeeded oppure failed.

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/v3/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/v3/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

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).

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? La sincronizzazione non avviene automaticamente al push. Chiama l’endpoint API di sincronizzazione oppure fai clic sul pulsante Sync nella UI.
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

​Guida introduttiva

​1. Crea il file blueprint

​2. Esegui il push al branch predefinito

​3. Verifica nella UI

​Come funziona la sincronizzazione

​Sync vs. build

​Sincronizzazione tramite l’API

​Flusso completo

​Passaggio 1: sincronizza il blueprint

​Passaggio 2: Avvia una build 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

Guida introduttiva

1. Crea il file blueprint

2. Esegui il push al branch predefinito

3. Verifica nella UI

Come funziona la sincronizzazione

Sync vs. build

Sincronizzazione tramite l’API

Flusso completo

Passaggio 1: sincronizza il blueprint

Passaggio 2: Avvia una build 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