Un blueprint definisce come viene configurato l’ambiente di Devin: quali strumenti installare, come mantenere aggiornate le dipendenze e quali comandi Devin deve conoscere.
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)
| Sezione | Scopo | Eseguito? |
|---|
initialize | Installa strumenti di sistema, runtime di linguaggio e CLI globali | Sì, durante ogni build |
maintenance | Installa e aggiorna le dipendenze del progetto | Sì, durante le build + all’inizio di ogni sessione |
knowledge | Indica a Devin come eseguire lint, test, build e altre operazioni specifiche del progetto | No, fornito come riferimento |
initialize viene eseguito solo durante le build. I risultati vengono salvati nello snapshot. maintenance viene eseguito durante le build (dopo initialize) e all’inizio di ogni sessione dopo aver aggiornato il codice all’ultima versione, quindi i comandi devono essere rapidi e incrementali. Le build vengono eseguite automaticamente quando il tuo blueprint cambia e periodicamente (circa ogni 24 ore).
Usa initialize per installare strumenti e runtime che non dipendono dallo stato specifico del tuo codice: runtime dei linguaggi, pacchetti di sistema, CLI globali.
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
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"
run.
Quando usare initialize anziché maintenance
Inserisci in initialize | Inserisci in maintenance |
|---|
| Installazione del runtime del linguaggio | npm install / pip install |
Pacchetti di sistema (apt-get) | bundle install |
| Strumenti CLI globali | go mod download |
| Configurazione una tantum | Aggiornamenti della cache delle dipendenze |
GitHub Actions (setup-python, etc.) | Script di configurazione specifici per repo |
initialize; i comandi per le dipendenze che si basano sui file di lock del codice vanno in maintenance.
Usa maintenance per installare le dipendenze e per altri comandi che devono essere eseguiti dopo il clone del codice. Qui vanno npm install, pip install, uv sync e comandi simili.
maintenance: |
npm install
pip install -r requirements.txt
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 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/
| Campo | Tipo | Descrizione |
|---|
name | string | Identificatore di questo elemento di conoscenza (ad es. lint, test, build) |
contents | string | Testo libero con comandi, istruzioni o note |
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
initialize o maintenance usa uno di due tipi: comandi shell (run) o GitHub Actions (uses).
Esegui comandi shell personalizzati in bash:
- name: "Install dependencies"
run: |
npm install
pip install -r requirements.txt
| Campo | Tipo | Descrizione |
|---|
name | string (optional) | Etichetta leggibile dall’utente del passaggio |
run | string | Comandi shell da eseguire |
env | map (optional) | Variabili d’ambiente aggiuntive per questo passaggio |
- 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.
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"
| Campo | Tipo | Descrizione |
|---|
name | string (opzionale) | Etichetta del passaggio leggibile dall’utente |
uses | string | Riferimento a una GitHub Action |
with | map (opzionale) | Parametri di input dell’azione |
env | map (opzionale) | Variabili d’ambiente aggiuntive per questo passaggio |
github.com/<owner>/<repo>@<ref>
github.com/<owner>/<repo>/<subpath>@<ref>
github.com/ e il suffisso @<ref> sono entrambi obbligatori. Il ref è in genere un tag di versione come v5.
Azioni di uso comune:
| Azione | Scopo | Esempio di with |
|---|
github.com/actions/setup-python@v5 | Installare Python | python-version: "3.12" |
github.com/actions/setup-node@v4 | Installare Node.js | node-version: "20" |
github.com/actions/setup-go@v5 | Installare Go | go-version: "1.22" |
github.com/actions/setup-java@v4 | Installare Java/JDK | java-version: "21", distribution: "temurin" |
github.com/gradle/actions/setup-gradle@v4 | Installare Gradle | (nessuno) |
github.com/ruby/setup-ruby@v1 | Installare Ruby | ruby-version: "3.3" |
Sono supportate solo le GitHub Actions basate su Node.js. Le azioni composite e quelle basate su Docker non sono supportate.
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"
setup-python aggiunge l’eseguibile di Python a PATH, che rimane disponibile in tutti i passaggi successivi e in maintenance.
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 progetto | Esiste una GitHub Action ufficiale per ciò che ti serve |
| Configuri file o l’ambiente | Vuoi la gestione automatica delle versioni e la cache |
| Il comando è semplice e indipendente | Useresti la stessa Action in un flusso di lavoro di GitHub Actions |
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
env:
- run: pip install -r requirements.txt
env:
PIP_INDEX_URL: "https://pypi.example.com/simple/"
PIP_BREAK_SYSTEM_PACKAGES: "1"
Variabili d’ambiente tra i passaggi ($ENVRC)
$ENVRC:
- name: "Set shared variables"
run: |
echo "DATABASE_URL=postgresql://localhost:5432/myapp" >> $ENVRC
echo "APP_ENV=development" >> $ENVRC
$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.
I segreti configurati nell’interfaccia di Devin (Settings > Secrets) 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 in Settings > Secrets.
- 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 in Settings > Secrets con ambito repo.
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 sia durante le build sia all’inizio di ogni sessione. 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 a ogni sessione, 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.
.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
FILE_.
Usa file allegati nei passaggi del blueprint:
maintenance:
- name: "Configure Maven"
run: |
mkdir -p ~/.m2
cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml
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 > Configurazione dell’ambiente.
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
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
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
