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 de premier niveau, ainsi qu’une section post-build pour les blueprints au niveau de l’org et de l’entreprise, et une section clone facultative pour les blueprints au niveau du dépôt :

initialize: ...   # Install tools and runtimes
maintenance: ...  # Install project dependencies
knowledge: ...    # Reference info for Devin (never executed)
post-build: ...   # (Org/enterprise uniquement) Commandes exécutées après toute la configuration
clone: ...        # (Repo-level only) Override git-clone defaults

Section	Objectif	Exécuté ?
`initialize`	Installer les outils système, les environnements d’exécution et les CLI globaux	Pendant les builds complets et pour les espaces de travail reconstruits
`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
`post-build`	Commandes qui s’exécutent une fois que tous les dépôts sont clonés et configurés (org/entreprise uniquement)	Oui, pendant les builds — un code de sortie non nul fait échouer le build
`clone`	Définir une dérogation à la façon dont le dépôt est cloné dans le snapshot (au niveau du dépôt uniquement)	Appliqué pendant l’étape de clonage du build

Toutes les sections sont facultatives. Vous pouvez inclure n’importe quelle combinaison. initialize s’exécute pendant les builds complets et pour les espaces de travail reconstruits à partir de zéro. Les résultats sont enregistrés dans le snapshot. Lors d’un build différentiel, les espaces de travail hérités ignorent initialize, récupèrent la dernière version du code et n’exécutent que maintenance. Écrivez maintenance de sorte qu’il soit autonome et puisse s’exécuter indépendamment sur le snapshot existant, sans nécessiter l’exécution immédiate préalable de initialize ni dépendre de variables d’environnement que initialize aurait précédemment écrites dans $ENVRC. 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 de l’environnement d’exécution 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 pendant les full builds. Dans les builds différentiels, les espaces de travail hérités ignorent initialize et n’exécutent que maintenance après avoir récupéré la dernière version du code. Les outils et les environnements d’exécution 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

post-build

La section post-build est disponible uniquement dans les blueprints au niveau de l’organisation et de l’entreprise (elle n’est pas prise en charge dans les blueprints au niveau du dépôt). Ses étapes s’exécutent pendant le build une fois que tous les dépôts ont été clonés et que leurs étapes initialize et maintenance sont terminées, mais avant la vérification d’état et la création de l’image snapshot. C’est donc l’endroit idéal pour les validations inter-dépôts et les vérifications d’état qui nécessitent un environnement entièrement assemblé. Comme elle s’exécute tard dans le build, lorsque l’ensemble de l’environnement est en place, une étape post-build peut accéder à chaque dépôt cloné et à chaque outil installé par les blueprints de l’entreprise, de l’organisation et du dépôt.

post-build: |
  # Vérifier que l'environnement assemblé est opérationnel
  node --version
  python --version
  test -d ~/repos/my-service

Ou sous forme structurée :

post-build:
  - name: "Verify toolchain"
    run: |
      node --version
      uv --version

  - name: "Smoke-test the workspace"
    run: ~/repos/my-service/scripts/healthcheck.sh

Les étapes post-build font échouer le build en cas de code de sortie non nul. Si une étape post-build se termine avec un code non nul, le build est marqué comme échoué et aucune image snapshot n’est produite. Utilisez ce mécanisme pour conditionner les snapshots à des vérifications d’état — mais assurez-vous que les commandes sont fiables afin qu’une vérification instable ne bloque pas vos builds.

Les étapes post-build utilisent les mêmes types d’étapes que initialize et maintenance (commandes shell run et uses de GitHub Actions), et s’exécutent depuis le répertoire personnel (~).

clone

Pour les blueprints au niveau du dépôt, la section facultative clone déroge aux valeurs par défaut utilisées lorsque Devin clone le dépôt dans le snapshot. Chaque champ est facultatif et, s’il n’est pas renseigné, une valeur par défaut appropriée est utilisée afin de préserver le comportement actuel.

clone:
  path: my-project        # destination du clone sous ~/repos/ (default: nom court du dépôt)
  ref: develop            # branche ou tag à extraire (default: branche par défaut du dépôt)
  depth: 1                # 0 = historique complet, N = --depth N (default: 0)
  tags: false             # false passe --no-tags (default: true)
  submodules: recursive   # true / false / "recursive" (default: true)
  lfs: false              # false définit GIT_LFS_SKIP_SMUDGE=1 lors du clone (default: true)

Champ	Type	Par défaut	Description
`path`	string	nom court du dépôt	Remplace le répertoire de destination du clonage sous `~/repos/`. Doit être unique parmi les dépôts d’un même snapshot.
`ref`	string	branche par défaut du dépôt	Branche ou tag sur lequel se positionner après le clonage. Les SHA de commit ne sont pas pris en charge ici.
`depth`	int	`0`	Profondeur de clonage. `0` clone l’historique complet ; toute valeur positive passe `--depth N` pour un clonage superficiel.
`tags`	bool	`true`	Lorsque `false`, passe `--no-tags` pour ne pas récupérer les tags Git.
`submodules`	bool or `"recursive"`	`true`	`true` ou `"recursive"` passe `--recurse-submodules`. `false` ignore complètement les sous-modules.
`lfs`	bool	`true`	Lorsque `false`, définit `GIT_LFS_SKIP_SMUDGE=1` pour ignorer le téléchargement des objets Git LFS pendant le clonage.

clone s’applique uniquement aux blueprints au niveau du dépôt — il contrôle la façon dont ce dépôt spécifique est cloné dans le snapshot. Il n’a aucun effet dans les blueprints au niveau de l’organisation ou au niveau de l’entreprise.

Types d’étapes

Chaque étape de initialize, maintenance ou post-build 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 produite par le build actuel. Cela fonctionne de manière similaire à $GITHUB_ENV dans GitHub Actions. Cela s’applique également à PATH. Si vous installez un outil dans un répertoire non standard (tout ce qui se trouve en dehors de /usr/bin ou /usr/local/bin), ajoutez ce répertoire à $ENVRC afin que les étapes suivantes et les blueprints au niveau du dépôt puissent trouver le binaire :

- name: "Install latest direnv"
  run: |
    curl -sfL https://direnv.net/install.sh | bash
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC

Un simple export PATH=... dans un bloc run: n’affecte que le shell de cette étape. Chaque étape démarre un nouveau processus shell, donc les modifications de PATH qui ne sont pas écrites dans $ENVRC sont perdues.

Les actions uses: (p. ex. actions/setup-node) répercutent automatiquement leurs ajouts à PATH dans $ENVRC — vous ne devez le faire manuellement que pour les étapes run:.

$ENVRC est réinitialisé au début de chaque build, y compris les builds différentiels. Les valeurs écrites pendant un build ne sont pas accessibles au build suivant. En particulier, un espace de travail hérité n’exécute que maintenance, il ne peut donc pas s’appuyer sur PATH ou d’autres variables que initialize a écrites dans $ENVRC lors du build parent. Configurez tout environnement requis par maintenance dans maintenance lui-même.

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 versionnés avec Git

Vous pouvez stocker des blueprints sous forme de fichiers .devin/blueprint.yaml directement dans votre dépôt, puis les synchroniser via l’API ou l’UI. Consultez blueprints versionnés avec Git pour les instructions de configuration et plus de détails.

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

​Vue d’ensemble

​initialize

​Forme simple

​Format structuré

​Quand utiliser initialize ou maintenance

​maintenance

​knowledge

​post-build

​clone

​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 versionnés avec 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

post-build

clone

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 versionnés avec Git

Exemple complet

Blueprint à l’échelle de l’organisation

Blueprint du dépôt