> ## Documentation Index > Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt > Use this file to discover all available pages before exploring further. # Blueprint supportati da Git > Archivia i blueprint come .devin/blueprint.yaml nel tuo repository e sincronizzali tramite l'API o la UI.
## 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](/it/onboard-devin/environment/blueprint-reference) 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: ```yaml theme={null} 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: 1. **Sincronizzazione tramite API** — Chiama l'endpoint di sincronizzazione v3 (vedi [Sincronizzazione tramite l'API](#sync-via-the-api) di seguito). È l'approccio consigliato per le pipeline CI/CD. 2. **Sincronizzazione tramite UI** — Fai clic sul pulsante **Sync** nel blueprint editor. Se il contenuto è cambiato, questo attiva anche uno snapshot build. 3. **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
```mermaid theme={null} sequenceDiagram participant Dev as Developer participant Git as Git Provider participant CI as CI/CD Pipeline participant API as Devin API Dev->>Git: Push/merge .devin/blueprint.yaml Git->>CI: Trigger post-merge workflow CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/sync API-->>CI: 200 OK (repo_name) CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/builds API-->>CI: 201 Created (build_id, status) CI->>API: GET /v3/organizations/{org_id}/snapshot-setup/builds/{build_id} API-->>CI: 200 OK (status: succeeded) ```
### Passaggio 1: sincronizza il blueprint
Scarica la versione più recente di `.devin/blueprint.yaml` dal branch predefinito: ```bash theme={null} 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: ```json theme={null} {"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: ```bash theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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: ```json theme={null} {"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: ```yaml theme={null} # .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](/it/api-reference/overview) 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
1. Apri l'editor dei blueprint in **Settings > Environment > Blueprints** 2. Modifica il file YAML nell'editor 3. Fai clic su **Create PR** 4. Devin apre una pull request nel tuo repository che aggiorna `.devin/blueprint.yaml` 5. Rivedi, approva ed esegui il merge della PR 6. 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
1. Modifica `.devin/blueprint.yaml` nel tuo IDE o sul tuo provider Git 2. Esegui il commit e il push sul branch predefinito (oppure apri una PR ed esegui il merge) 3. 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](#sync-via-the-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: ```yaml theme={null} # 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`: ```yaml theme={null} # my-repo/packages/frontend/.devin/blueprint.yaml maintenance: | pnpm build knowledge: - name: lint contents: pnpm lint - name: test contents: pnpm test ``` ```yaml theme={null} # 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: 1. Crea `.devin/blueprint.yaml` nel repository con il contenuto desiderato 2. Esegui il push nel branch predefinito 3. Nell'editor del blueprint, fai clic sul menu a discesa della sorgente e seleziona il provider Git desiderato (ad es. "GitHub") 4. 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: 1. Nel blueprint editor, fai clic sul menu a discesa della sorgente e seleziona **Database** 2. Il contenuto attuale viene mantenuto, ma i futuri push a `.devin/blueprint.yaml` non aggiorneranno più il blueprint 3. 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: ```yaml theme={null} # 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](/it/onboard-devin/environment/windows-support) 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 `/.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.