Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.devin.ai/llms.txt

Use this file to discover all available pages before exploring further.

Questo è il riferimento completo ai campi dei blueprint. Per un’introduzione ai blueprint e a come si inseriscono nell’ambiente di Devin, consulta Configurazione dichiarativa dell’ambiente.
Un blueprint definisce come viene configurato l’ambiente di Devin: quali strumenti installare, come mantenere aggiornate le dipendenze e quali comandi Devin deve conoscere.

​
Panoramica

Un blueprint comprende tre sezioni di primo livello: 
initialize: ...   # Installa strumenti e runtime
maintenance: ...  # Installa le dependencies del progetto
knowledge: ...    # Informazioni di riferimento per Devin (mai eseguite)
SezioneScopoEseguito?
initializeInstalla strumenti di sistema, runtime di linguaggio e CLI globaliSì, durante ogni build
maintenanceInstalla e aggiorna le dipendenze del progettoSì, durante le build. Presentato all’agent all’inizio della sessione (non eseguito automaticamente).
knowledgeIndica a Devin come eseguire lint, test, build e altre operazioni specifiche del progettoNo, fornito come riferimento
Tutte e tre le sezioni sono facoltative. Puoi includerne qualsiasi combinazione. initialize viene eseguito solo durante le build. I risultati vengono salvati nello snapshot. maintenance viene eseguito durante le build (dopo initialize). All’inizio di ogni sessione, i comandi di maintenance non vengono eseguiti automaticamente — vengono invece presentati all’agent come contesto, così sa quali comandi per le dipendenze eseguire se necessario (ad es. dopo aver aggiornato il codice all’ultima versione). I comandi devono comunque essere rapidi e incrementali. Le build vengono eseguite automaticamente quando il tuo blueprint cambia e periodicamente (circa ogni 24 ore).

​
initialize

Usa initialize per installare strumenti e runtime che non dipendono dallo stato specifico del tuo codice: runtime dei linguaggi, pacchetti di sistema, CLI globali.

​
Forma semplice

Per i comandi shell più semplici, usa uno scalare a blocco: 
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  apt-get update && apt-get install -y build-essential
  npm install -g pnpm

​
Formato strutturato

Per i passaggi denominati, le variabili d’ambiente o le GitHub Actions, usa un elenco: 
initialize:
  - name: "Install Python 3.12"
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

  - name: "Install system packages"
    run: |
      apt-get update
      apt-get install -y libpq-dev

  - name: "Install global tools"
    run: pip install uv
    env:
      PIP_BREAK_SYSTEM_PACKAGES: "1"
Le due forme possono essere combinate. La forma semplice equivale a un unico passaggio con run.

​
Quando usare initialize anziché maintenance

Inserisci in initializeInserisci in maintenance
Installazione del runtime del linguaggionpm install / pip install
Pacchetti di sistema (apt-get)bundle install
Strumenti CLI globaligo mod download
Configurazione una tantumAggiornamenti della cache delle dipendenze
GitHub Actions (setup-python, etc.)Script di configurazione specifici per repo
Entrambe le sezioni vengono eseguite a ogni build, ma questa distinzione rende la configurazione più leggibile. Strumenti e runtime vanno in initialize; i comandi per le dipendenze che si basano sui file di lock del codice vanno in maintenance.

​
maintenance

Usa maintenance per installare le dipendenze e per altri comandi che devono essere eseguiti dopo il clone del codice. Questi comandi vengono eseguiti durante le build e vengono esposti all’agente all’inizio della sessione, così che possa eseguirli di nuovo se le dipendenze sono cambiate. Qui vanno npm install, pip install, uv sync e comandi simili. 
maintenance: |
  npm install
  pip install -r requirements.txt
Oppure in formato strutturato: 
maintenance:
  - name: "Install npm dependencies"
    run: npm install

  - name: "Install Python dependencies"
    run: uv sync
    env:
      UV_CACHE_DIR: /tmp/uv-cache
Per i blueprint a livello di repo, i comandi maintenance vengono eseguiti dalla directory radice del repository. Per i blueprint a livello di org, vengono eseguiti dalla home directory (~).

​
knowledge

La sezione knowledge non viene eseguita. Fornisce informazioni di riferimento che Devin utilizza quando lavora nel tuo progetto. È qui che indichi a Devin i comandi corretti per il linting, il testing, la build e qualsiasi altro flusso di lavoro specifico del progetto. 
knowledge:
  - name: lint
    contents: |
      Run linting with:
      npm run lint

      For auto-fix:
      npm run lint -- --fix

  - name: test
    contents: |
      Run the full test suite:
      npm test

      Run a single test file:
      npm test -- path/to/test.ts

  - name: build
    contents: |
      npm run build

      Build output goes to dist/
Ogni elemento di conoscenza include:
CampoTipoDescrizione
namestringIdentificatore di questo elemento di conoscenza (ad es. lint, test, build)
contentsstringTesto libero con comandi, istruzioni o note
Il campo name è un’etichetta. Per convenzione, lint, test e build sono i nomi standard. Devin fa riferimento a questi nomi quando verifica il proprio lavoro. Puoi aggiungere altri elementi di conoscenza con nomi personalizzati: 
knowledge:
  - name: lint
    contents: ...
  - name: test
    contents: ...
  - name: build
    contents: ...
  - name: deploy
    contents: |
      Deploy to staging:
      npm run deploy:staging
  - name: database
    contents: |
      Run migrations:
      npm run db:migrate

      Seed test data:
      npm run db:seed

​
Tipi di passaggi

Ogni passaggio in initialize o maintenance usa uno di due tipi: comandi shell (run) o GitHub Actions (uses).

​
Comandi shell (run)

Esegui comandi shell personalizzati in bash: 
- name: "Install dependencies"
  run: |
    npm install
    pip install -r requirements.txt
CampoTipoDescrizione
namestring (optional)Etichetta leggibile dall’utente del passaggio
runstringComandi shell da eseguire
envmap (optional)Variabili d’ambiente aggiuntive per questo passaggio
Dettagli di esecuzione:
  • I comandi vengono eseguiti in bash. Se un comando in uno script su più righe non riesce, l’intero passaggio si interrompe immediatamente.
  • I blueprint a livello di org vengono eseguiti nella directory home (~).
  • I blueprint a livello di repo vengono eseguiti nella directory radice del repository clonato.
  • Ogni passaggio ha un timeout di 1 ora.
  • I secret sono automaticamente disponibili come variabili d’ambiente.

​
GitHub Actions (uses)

Esegui direttamente nel tuo blueprint le GitHub Actions basate su Node.js: 
- name: "Install Python"
  uses: github.com/actions/setup-python@v5
  with:
    python-version: "3.12"
CampoTipoDescrizione
namestring (opzionale)Etichetta del passaggio leggibile dall’utente
usesstringRiferimento a una GitHub Action
withmap (opzionale)Parametri di input dell’azione
envmap (opzionale)Variabili d’ambiente aggiuntive per questo passaggio
Formato del riferimento dell’azione: 
github.com/<owner>/<repo>@<ref>
github.com/<owner>/<repo>/<subpath>@<ref>
Il prefisso github.com/ e il suffisso @<ref> sono entrambi obbligatori. Il ref è in genere un tag di versione come v5. Azioni di uso comune:
AzioneScopoEsempio di with
github.com/actions/setup-python@v5Installare Pythonpython-version: "3.12"
github.com/actions/setup-node@v4Installare Node.jsnode-version: "20"
github.com/actions/setup-go@v5Installare Gogo-version: "1.22"
github.com/actions/setup-java@v4Installare Java/JDKjava-version: "21", distribution: "temurin"
github.com/gradle/actions/setup-gradle@v4Installare Gradle(nessuno)
github.com/ruby/setup-ruby@v1Installare Rubyruby-version: "3.3"
Sono supportate solo le GitHub Actions basate su Node.js. Le azioni composite e quelle basate su Docker non sono supportate.
Come funzionano i valori di with: I valori passati tramite with vengono forniti all’azione come input, seguendo le stesse convenzioni dei flussi di lavoro di GitHub Actions. Tutti i valori vengono convertiti in stringhe. 
with:
  python-version: "3.12"
  check-latest: true
  cache: "pip"
Come le azioni propagano le modifiche: Le azioni possono modificare l’ambiente per i passaggi successivi. Ad esempio, setup-python aggiunge l’eseguibile di Python a PATH, che rimane disponibile in tutti i passaggi successivi e in maintenance.

​
run vs uses: quale usare

Usa run quando…Usa uses quando…
Installi pacchetti di sistema (apt-get)Imposti i runtime dei linguaggi (Python, Node, Go, Java, Ruby)
Esegui script specifici del progettoEsiste una GitHub Action ufficiale per ciò che ti serve
Configuri file o l’ambienteVuoi la gestione automatica delle versioni e la cache
Il comando è semplice e indipendenteUseresti la stessa Action in un flusso di lavoro di GitHub Actions
In pratica, nella maggior parte delle configurazioni si usa uses per i runtime dei linguaggi e run per tutto il resto.

​
Variabili d’ambiente e segreti

​
Variabili d’ambiente a livello di singolo passaggio

Qualsiasi passaggio può definire variabili d’ambiente aggiuntive tramite il campo env: 
- run: pip install -r requirements.txt
  env:
    PIP_INDEX_URL: "https://pypi.example.com/simple/"
    PIP_BREAK_SYSTEM_PACKAGES: "1"
Queste sono limitate a questo passaggio e non persistono nei passaggi successivi.

​
Variabili d’ambiente tra i passaggi ($ENVRC)

Per rendere disponibili le variabili d’ambiente tra i vari passaggi, scrivile nel file $ENVRC: 
- name: "Set shared variables"
  run: |
    echo "DATABASE_URL=postgresql://localhost:5432/myapp" >> $ENVRC
    echo "APP_ENV=development" >> $ENVRC
Le variabili scritte in $ENVRC vengono esportate automaticamente e sono disponibili in tutti i passaggi successivi e nella sessione di Devin. Funziona in modo analogo a $GITHUB_ENV in GitHub Actions.

​
Segreti

I segreti configurati nell’interfaccia di Devin (tramite la scheda Secrets in ogni editor di blueprint) vengono iniettati automaticamente come variabili d’ambiente. Non devi dichiararli nel blueprint. Ti basta richiamarli per nome (ad es. $MY_SECRET). I segreti vengono iniettati prima dell’esecuzione di ogni passaggio durante le build e nuovamente all’inizio di ogni sessione. Vengono rimossi dall’immagine snapshot stessa, quindi le credenziali non vengono mai incorporate nelle immagini macchina salvate.
  • Segreti dell’organizzazione: Disponibili come variabili d’ambiente in ogni passaggio di tutti i blueprint dell’org. Impostali nella scheda Secrets dell’editor del blueprint per tutta l’org.
  • Segreti Enterprise: Uniti ai segreti dell’org (i segreti dell’org hanno la precedenza in caso di conflitto di nomi). Disponibili in tutte le org dell’Enterprise.
  • Segreti del repository: Scritti in un file dedicato per repo in /run/repo_secrets/{owner/repo}/.env.secrets. Durante le build, i segreti del repo vengono caricati automaticamente prima dell’esecuzione dei passaggi del blueprint di quel repo. Durante la sessione, Devin li carica quando lavora nel repo. Configurali nella scheda Secrets dell’editor del blueprint del repository.
Segreti solo build: I segreti contrassegnati come “build only” sono disponibili durante le build snapshot, ma vengono rimossi prima che lo snapshot venga salvato. Usali per credenziali necessarie solo in fase di build (ad es. per scaricare artifact privati durante initialize).
maintenance viene eseguito durante le build. All’inizio della sessione, i comandi maintenance vengono esposti all’agente (non eseguiti automaticamente), quindi l’agente può eseguirli di nuovo se necessario. Se un passaggio maintenance scrive segreti nei file di configurazione (ad es. ~/.m2/settings.xml, ~/.npmrc), questi file verranno incorporati nello snapshot. Inserisci i passaggi che scrivono credenziali in maintenance (non in initialize) in modo che vengano aggiornati durante le build periodiche, ma tieni presente che i file generati restano nell’immagine. Per la massima sicurezza, usa variabili d’ambiente o $ENVRC invece di scrivere le credenziali su disco.

​
File allegati

Puoi caricare file (come .npmrc, settings.xml e file di configurazione) tramite l’editor dei blueprint. I file caricati vengono salvati in ~/.files/ e viene impostata una variabile d’ambiente che punta al percorso di ciascun file: 
$FILE_SETTINGS_XML    -> /home/ubuntu/.files/settings.xml
$FILE_NPMRC           -> /home/ubuntu/.files/.npmrc
Il nome della variabile deriva dal nome del file: in maiuscolo, con i caratteri non alfanumerici sostituiti da trattini bassi e con il prefisso FILE_. Usa file allegati nei passaggi del blueprint: 
maintenance:
  - name: "Configure Maven"
    run: |
      mkdir -p ~/.m2
      cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml

​
Blueprint basati su Git

I blueprint basati su Git non sono ancora supportati. Questa funzionalità arriverà presto. Potrai archiviare i blueprint nel tuo repository e fare in modo che le build vengano avviate automaticamente quando cambiano. Per ora, configura i blueprint dall’interfaccia utente in Settings > Environment > Blueprints.

​
Esempio completo

Per capire come i blueprint si compongono nei vari livelli (enterprise → org → repo), gli stati delle build, gli stati del repository e cosa attiva una nuova build, consulta Build e sessioni nella pagina della configurazione dichiarativa.

​
Blueprint per tutta l’org

Strumenti condivisi necessari a ogni repo dell’org. Viene eseguito per primo (dopo eventuali blueprint Enterprise), nella directory home. 
initialize:
  - name: "Install Node.js 20"
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: "Install Python 3.12 and uv"
    run: |
      curl -LsSf https://astral.sh/uv/install.sh | sh

  - name: "Install shared tools"
    run: |
      npm install -g pnpm turbo
      apt-get update && apt-get install -y jq ripgrep

  - name: "Configure private registry"
    run: |
      echo "//npm.corp.example.com/:_authToken=$NPM_REGISTRY_TOKEN" >> ~/.npmrc

​
Blueprint a livello di repo

Configurazione specifica del progetto per un monorepo Node.js + Python. Viene eseguito dopo il blueprint per tutta l’org, nella directory del repository. 
initialize:
  - name: "Install Playwright browsers"
    run: npx playwright install --with-deps chromium

  - name: "Set up project environment variables"
    run: |
      echo "DATABASE_URL=postgresql://localhost:5432/myapp_dev" >> $ENVRC
      echo "REDIS_URL=redis://localhost:6379" >> $ENVRC
      echo "APP_ENV=development" >> $ENVRC

maintenance:
  - name: "Install frontend dependencies"
    run: |
      cd frontend
      pnpm install

  - name: "Install backend dependencies"
    run: |
      cd backend
      uv sync

  - name: "Run database migrations"
    run: |
      cd backend
      uv run alembic upgrade head
    env:
      DATABASE_URL: "postgresql://localhost:5432/myapp_dev"

knowledge:
  - name: lint
    contents: |
      Frontend:
      cd frontend && pnpm lint

      Backend:
      cd backend && uv run ruff check .

      Auto-fix:
      cd frontend && pnpm lint --fix
      cd backend && uv run ruff check --fix .

  - name: test
    contents: |
      Frontend unit tests:
      cd frontend && pnpm test

      Backend unit tests:
      cd backend && uv run pytest

      E2E tests (requires dev server running):
      cd frontend && pnpm test:e2e

  - name: build
    contents: |
      Frontend:
      cd frontend && pnpm build

      Backend:
      cd backend && uv run python -m build

  - name: dev-server
    contents: |
      Start the full development stack:
      cd backend && uv run uvicorn main:app --reload &
      cd frontend && pnpm dev

      Frontend: http://localhost:3000
      Backend API: http://localhost:8000
      API docs: http://localhost:8000/docs

  - name: database
    contents: |
      Run migrations:
      cd backend && uv run alembic upgrade head

      Create a new migration:
      cd backend && uv run alembic revision --autogenerate -m "description"

      Reset the database:
      cd backend && uv run alembic downgrade base && uv run alembic upgrade head