Référence des blueprints

Il s’agit de la référence complète des champs des blueprints. Pour une introduction aux blueprints et à leur place dans l’environnement de Devin, consultez Configuration déclarative de l’environnement.

Un blueprint définit la configuration de l’environnement de Devin : quels outils installer, comment maintenir les dépendances à jour et quelles commandes Devin doit connaître.

Vue d’ensemble

Un blueprint comporte trois sections principales :

initialize: ...   # Installer les outils et les environnements d'exécution
maintenance: ...  # Installer les dépendances du projet
knowledge: ...    # Informations de référence pour Devin (jamais exécutées)

Section	Objectif	Exécuté ?
`initialize`	Installer les outils système, les environnements d’exécution et les CLI globaux	Oui, à chaque build
`maintenance`	Installer et mettre à jour les dépendances du projet	Oui, pendant les builds. Présenté à l’agent au démarrage de la session (non exécuté automatiquement).
`knowledge`	Indiquer à Devin comment exécuter le lint, les tests, le build, ainsi que d’autres informations spécifiques au projet	Non, fourni à titre de référence

Les trois sections sont facultatives. Vous pouvez inclure n’importe quelle combinaison. initialize s’exécute uniquement pendant les builds. Les résultats sont enregistrés dans le snapshot. maintenance s’exécute pendant les builds (après initialize). Au début de chaque session, les commandes maintenance ne sont pas exécutées automatiquement ; elles sont plutôt présentées à l’agent comme contexte afin qu’il sache quelles commandes de dépendance exécuter si nécessaire (par ex. après avoir récupéré la dernière version du code). Les commandes doivent toujours être rapides et incrémentales. Les builds s’exécutent automatiquement lorsque votre blueprint change et périodiquement (toutes les ~24 heures).

initialize

Utilisez initialize pour installer des outils et des environnements d’exécution qui ne dépendent pas de l’état spécifique de votre code : environnements d’exécution de langage, packages système et CLI globaux.

Forme simple

Pour les commandes shell simples, utilisez un bloc scalaire :

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  apt-get update && apt-get install -y build-essential
  npm install -g pnpm

Format structuré

Pour les étapes nommées, les variables d’environnement ou GitHub Actions, utilisez une liste :

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"

Les deux formes peuvent être utilisées ensemble. La forme simple équivaut à une seule étape avec run.

Quand utiliser `initialize` ou `maintenance`

À mettre dans `initialize`	À mettre dans `maintenance`
Installation du runtime du langage	`npm install` / `pip install`
Packages système (`apt-get`)	`bundle install`
Outils CLI globaux	`go mod download`
Configuration ponctuelle	Mises à jour du cache des dépendances
GitHub Actions (`setup-python`, etc.)	Scripts de configuration spécifiques au dépôt

Les deux sections s’exécutent à chaque build, mais cette séparation rend votre configuration plus lisible. Les outils et les runtimes vont dans initialize ; les commandes de dépendances liées aux fichiers de verrouillage de votre code vont dans maintenance.

maintenance

Utilisez maintenance pour installer les dépendances et exécuter les autres commandes qui doivent l’être après le clonage de votre code. Ces commandes s’exécutent pendant les builds et sont présentées à l’Agent au démarrage de la session afin qu’il puisse les relancer si les dépendances ont changé. C’est à cet endroit que doivent figurer npm install, pip install, uv sync et autres commandes similaires.

maintenance: |
  npm install
  pip install -r requirements.txt

Ou sous forme structurée :

maintenance:
  - name: "Install npm dependencies"
    run: npm install

  - name: "Install Python dependencies"
    run: uv sync
    env:
      UV_CACHE_DIR: /tmp/uv-cache

Pour les blueprints au niveau du dépôt, les commandes maintenance s’exécutent depuis le répertoire racine du dépôt. Pour les blueprints au niveau de l’organisation, elles s’exécutent depuis le répertoire personnel (~).

knowledge

La section knowledge n’est pas exécutée. Elle fournit des informations de référence que Devin utilise lorsqu’il travaille sur votre projet. C’est ainsi que vous indiquez à Devin les commandes appropriées pour le linting, les tests, la build et tout autre workflow spécifique au projet.

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/

Chaque élément de Knowledge comporte :

Champ	Type	Description
`name`	string	Identifiant de cet élément de Knowledge (p. ex., `lint`, `test`, `build`)
`contents`	string	Texte libre contenant des commandes, des instructions ou des notes

Le champ name est un libellé. Par convention, lint, test et build sont les noms standard. Devin s’y réfère lorsqu’il vérifie son travail. Vous pouvez ajouter d’autres éléments de Knowledge avec des noms personnalisés :

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

Types d’étapes

Chaque étape de initialize ou maintenance utilise l’un des deux types suivants : les commandes shell (run) ou les GitHub Actions (uses).

Commandes shell (`run`)

Exécutez les commandes shell de votre choix dans bash :

- name: "Install dependencies"
  run: |
    npm install
    pip install -r requirements.txt

Champ	Type	Description
`name`	string (optional)	Libellé explicite pour l’étape
`run`	string	Commande(s) shell à exécuter
`env`	map (optional)	Variables d’environnement supplémentaires pour cette étape

Détails d’exécution :

Les commandes s’exécutent dans bash. Si une commande d’un script sur plusieurs lignes échoue, l’étape entière s’arrête immédiatement.
Les blueprints au niveau de l’organisation s’exécutent dans le répertoire personnel (~).
Les blueprints au niveau du dépôt s’exécutent à la racine du dépôt cloné.
Chaque étape a un délai d’expiration d’une heure.
Les secrets sont automatiquement disponibles sous forme de variables d’environnement.

GitHub Actions (`uses`)

Exécutez directement des GitHub Actions basées sur Node.js dans votre blueprint :

- name: "Install Python"
  uses: github.com/actions/setup-python@v5
  with:
    python-version: "3.12"

Champ	Type	Description
`name`	string (optional)	Libellé explicite de l’étape
`uses`	string	Référence d’action GitHub
`with`	map (optional)	Paramètres d’entrée pour l’action
`env`	map (optional)	Variables d’environnement supplémentaires pour cette étape

Format de référence de l’action :

github.com/<owner>/<repo>@<ref>
github.com/<owner>/<repo>/<subpath>@<ref>

Le préfixe github.com/ et le suffixe @<ref> sont tous deux obligatoires. La référence est généralement une balise de version comme v5. Actions couramment utilisées :

Action	Objectif	Exemple de `with`
`github.com/actions/setup-python@v5`	Installer Python	`python-version: "3.12"`
`github.com/actions/setup-node@v4`	Installer Node.js	`node-version: "20"`
`github.com/actions/setup-go@v5`	Installer Go	`go-version: "1.22"`
`github.com/actions/setup-java@v4`	Installer Java/JDK	`java-version: "21"`, `distribution: "temurin"`
`github.com/gradle/actions/setup-gradle@v4`	Installer Gradle	(aucun)
`github.com/ruby/setup-ruby@v1`	Installer Ruby	`ruby-version: "3.3"`

Seules les GitHub Actions basées sur Node.js sont prises en charge. Les actions composites et les actions basées sur Docker ne sont pas prises en charge.

Fonctionnement des valeurs with : Les valeurs transmises via with sont fournies à l’action sous forme d’entrées, selon les mêmes conventions que dans les workflows GitHub Actions. Toutes les valeurs sont converties en chaînes de caractères.

with:
  python-version: "3.12"
  check-latest: true
  cache: "pip"

Comment les actions propagent les modifications : Les actions peuvent modifier l’environnement pour les étapes suivantes. Par exemple, setup-python ajoute l’exécutable Python au PATH, qui reste ensuite disponible pour toutes les étapes ultérieures ainsi que dans maintenance.

`run` vs `uses` : lequel utiliser

Utilisez `run` lorsque…	Utilisez `uses` lorsque…
Vous installez des packages système (`apt-get`)	Vous configurez des environnements d’exécution (Python, Node, Go, Java, Ruby)
Vous exécutez des scripts spécifiques au projet	Une GitHub Action officielle existe pour ce dont vous avez besoin
Vous configurez des fichiers ou l’environnement	Vous voulez une gestion automatique des versions et de la mise en cache
La commande est simple et autonome	Vous utiliseriez la même Action dans un workflow GitHub Actions

En pratique, la plupart des configurations utilisent uses pour les environnements d’exécution et run pour tout le reste.

Variables d’environnement et secrets

Variables d’environnement propres à l’étape

Chaque étape peut définir des variables d’environnement supplémentaires à l’aide du champ env :

- run: pip install -r requirements.txt
  env:
    PIP_INDEX_URL: "https://pypi.example.com/simple/"
    PIP_BREAK_SYSTEM_PACKAGES: "1"

Ils sont limités à l’étape et ne sont pas conservés pour les étapes suivantes.

Variables d’environnement d’une étape à l’autre (`$ENVRC`)

Pour transmettre des variables d’environnement d’une étape à l’autre, écrivez-les dans le fichier $ENVRC :

- name: "Set shared variables"
  run: |
    echo "DATABASE_URL=postgresql://localhost:5432/myapp" >> $ENVRC
    echo "APP_ENV=development" >> $ENVRC

Les variables écrites dans $ENVRC sont automatiquement exportées et accessibles à toutes les étapes suivantes ainsi qu’à la session Devin. Cela fonctionne de manière similaire à $GITHUB_ENV dans GitHub Actions.

Secrets

Les secrets configurés dans l’interface de Devin (via l’onglet Secrets dans chaque éditeur de blueprint) sont automatiquement injectés sous forme de variables d’environnement. Vous n’avez pas besoin de les déclarer dans votre blueprint. Référencez-les simplement par leur nom (p. ex., $MY_SECRET). Les secrets sont injectés avant l’exécution de chaque étape pendant les builds et réinjectés au début de chaque session. Ils sont supprimés de l’image du snapshot elle-même, de sorte que les identifiants ne sont jamais intégrés aux images de machine enregistrées.

Secrets d’organisation : disponibles sous forme de variables d’environnement à chaque étape dans tous les blueprints de l’organisation. Définissez-les dans l’onglet Secrets de l’éditeur du blueprint à l’échelle de l’organisation.
Secrets Enterprise : fusionnés avec les secrets d’organisation (les secrets d’organisation sont prioritaires en cas de conflit de nom). Disponibles dans toutes les organisations de l’enterprise.
Secrets du dépôt : écrits dans un fichier par dépôt à l’emplacement /run/repo_secrets/{owner/repo}/.env.secrets. Pendant les builds, les secrets du dépôt sont automatiquement chargés avant l’exécution des étapes du blueprint de ce dépôt. En session, Devin les charge lorsqu’il travaille dans le dépôt. Configurez-les dans l’onglet Secrets de l’éditeur du blueprint du dépôt.

Secrets réservés au build : les secrets marqués comme “build only” sont disponibles pendant les builds de snapshot, mais supprimés avant l’enregistrement du snapshot. Utilisez-les pour les identifiants nécessaires uniquement au moment du build (p. ex., pour télécharger des artefacts privés pendant initialize).

maintenance s’exécute pendant les builds. Au démarrage de la session, les commandes maintenance sont présentées à l’agent (elles ne sont pas exécutées automatiquement), de sorte que l’agent peut les relancer si nécessaire. Si une étape maintenance écrit des secrets dans des fichiers de configuration (p. ex., ~/.m2/settings.xml, ~/.npmrc), ces fichiers seront intégrés au snapshot. Placez les étapes qui écrivent des identifiants dans maintenance (et non dans initialize) afin qu’elles soient réactualisées lors des builds périodiques, mais gardez à l’esprit que les fichiers ainsi écrits persistent dans l’image. Pour une sécurité maximale, utilisez des variables d’environnement ou $ENVRC au lieu d’écrire des identifiants sur le disque.

Fichiers joints

Vous pouvez téléverser des fichiers (comme .npmrc, settings.xml ou des fichiers de configuration) dans l’éditeur de blueprint. Les fichiers téléversés sont enregistrés dans ~/.files/, et une variable d’environnement est définie pour pointer vers le chemin de chaque fichier :

$FILE_SETTINGS_XML    -> /home/ubuntu/.files/settings.xml
$FILE_NPMRC           -> /home/ubuntu/.files/.npmrc

Le nom de la variable est dérivé du nom du fichier : en majuscules, avec les caractères non alphanumériques remplacés par des traits de soulignement, et préfixé par FILE_. Utilisez des fichiers joints dans les étapes de votre blueprint :

maintenance:
  - name: "Configure Maven"
    run: |
      mkdir -p ~/.m2
      cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml

Blueprints basés sur Git

Les blueprints basés sur Git ne sont pas encore pris en charge. Cette fonctionnalité sera bientôt disponible. Vous pourrez stocker des blueprints dans votre dépôt et déclencher automatiquement des builds lorsqu’ils sont modifiés. Pour l’instant, configurez les blueprints via l’interface utilisateur, dans Settings > Environnement > Blueprints.

Exemple complet

Pour savoir comment les blueprints s’articulent entre les niveaux (entreprise → org → repo), les statuts de build, les états du dépôt et ce qui déclenche une reconstruction, consultez Builds et sessions sur la page de configuration déclarative.

Blueprint à l’échelle de l’organisation

Outils partagés dont chaque dépôt de l’organisation a besoin. Il est exécuté en premier (après tout blueprint Enterprise), dans le répertoire personnel.

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 du dépôt

Configuration spécifique au projet pour un monorepo Node.js + Python. Ce blueprint s’exécute après le blueprint à l’échelle de l’organisation, dans le répertoire du dépôt.

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

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Référence des blueprints

Vue d’ensemble

initialize

Forme simple

Format structuré

Quand utiliser `initialize` ou `maintenance`

maintenance

knowledge

Types d’étapes

Commandes shell (`run`)

GitHub Actions (`uses`)

`run` vs `uses` : lequel utiliser

Variables d’environnement et secrets

Variables d’environnement propres à l’étape

Variables d’environnement d’une étape à l’autre (`$ENVRC`)

Secrets

Fichiers joints

Blueprints basés sur Git

Exemple complet

Blueprint à l’échelle de l’organisation

Blueprint du dépôt

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Documentation Index

​Vue d’ensemble

​initialize

​Forme simple

​Format structuré

​Quand utiliser initialize ou maintenance

​maintenance

​knowledge

​Types d’étapes

​Commandes shell (run)

​GitHub Actions (uses)

​run vs uses : lequel utiliser

​Variables d’environnement et secrets

​Variables d’environnement propres à l’étape

​Variables d’environnement d’une étape à l’autre ($ENVRC)

​Secrets

​Fichiers joints

​Blueprints basés sur Git

​Exemple complet

​Blueprint à l’échelle de l’organisation

​Blueprint du dépôt

Vue d’ensemble

initialize

Forme simple

Format structuré

Quand utiliser `initialize` ou `maintenance`

maintenance

knowledge

Types d’étapes

Commandes shell (`run`)

GitHub Actions (`uses`)

`run` vs `uses` : lequel utiliser

Variables d’environnement et secrets

Variables d’environnement propres à l’étape

Variables d’environnement d’une étape à l’autre (`$ENVRC`)

Secrets

Fichiers joints

Blueprints basés sur Git

Exemple complet

Blueprint à l’échelle de l’organisation

Blueprint du dépôt