Blueprints adossés à Git

Vue d’ensemble

Les blueprints adossés à Git vous permettent de stocker la configuration de votre environnement directement dans votre repository sous la forme d’un fichier .devin/blueprint.yaml. Vous synchronisez ce fichier avec Devin via l’API ou l’interface utilisateur, puis vous déclenchez un build du snapshot pour appliquer les modifications. Vous bénéficiez ainsi du même workflow que pour le code de votre application : modifier dans votre IDE, ouvrir une pull request, obtenir une review, merger, puis synchroniser et lancer un build via une étape de CI ou l’interface utilisateur.

Approche	Emplacement du blueprint	Mode de modification	Application des modifications
Adossé à Git	`.devin/blueprint.yaml` dans votre repository	Modifier dans votre IDE, merger une PR	Appeler l’API de synchronisation (ou cliquer sur Sync dans l’interface utilisateur), puis déclencher un build — ou activer la synchronisation et le build à chaque commit sur la branche par défaut
Base de données	L’interface Settings de Devin	Modifier dans le navigateur	Enregistré immédiatement au clic

Comment Devin choisit le mode lorsque vous ajoutez un repository

Le mode adossé à Git est utilisé par défaut dès qu’un fichier blueprint est présent dans le repo. Lorsque vous ajoutez un repository à votre environnement, Devin vérifie la présence de .devin/blueprint.yaml sur la branche par défaut :

Si le fichier existe, Devin récupère le blueprint depuis Git (mode adossé à Git) et enregistre le commit SHA depuis lequel il a été synchronisé.
Si le fichier est absent (ou si la détection échoue), Devin crée un blueprint vide que vous gérez dans l’interface Settings (mode base de données).

Vous pouvez basculer un repository entre les deux modes à tout moment — consultez Basculer entre les modes Git et base de données.

Les blueprints adossés à Git utilisent le même format YAML que l’éditeur de l’interface utilisateur. Consultez la référence Blueprint pour la spécification complète des champs.

Premiers pas

1. Créer le fichier blueprint

Ajoutez un fichier .devin/blueprint.yaml à la racine de votre dépôt :

my-repo/
  .devin/
    blueprint.yaml
  src/
  package.json
  ...

Le fichier utilise le même format YAML que l’éditeur de l’interface utilisateur :

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. Pousser sur la branche par défaut

Validez puis poussez .devin/blueprint.yaml sur la branche par défaut de votre repository (généralement main ou master). Si le repository est déjà connecté à l’environnement de Devin, vous devez déclencher une synchronisation (via l’API ou le bouton Sync de l’interface utilisateur) pour que Devin prenne en compte le fichier, sauf si le blueprint est déjà en mode adossé à Git et que l’option Run on every commit to default branch est activée pour le repository. Si le blueprint est en mode base de données, basculez-le vers Git pour importer le fichier. Si vous ajoutez le repository pour la première fois, lors de la détection initiale, Devin lit le blueprint depuis Git.

3. Vérifiez dans l’UI

Accédez à Settings > Environment > Blueprints et cliquez sur le dépôt. L’éditeur affiche le contenu du blueprint issu de Git, et l’indicateur de source affiche le nom du fournisseur (p. ex. « GitHub ») avec le SHA du commit synchronisé.

Comment fonctionne la synchronisation

La synchronisation consiste à récupérer .devin/blueprint.yaml depuis le HEAD de la branche par défaut du dépôt et à mettre à jour les versions du blueprint stockées par Devin. Par défaut, la synchronisation ne s’effectue pas automatiquement lors d’un push. Elle s’exécute dans les cas suivants :

Synchronisation via l’API — Appelez l’endpoint de synchronisation (bêta) (voir Synchronisation via l’API ci-dessous). Il s’agit de l’approche recommandée pour les pipelines CI/CD.
Synchronisation via l’UI — Cliquez sur le bouton Sync dans l’éditeur de blueprint. Cela déclenche également un build du snapshot si le contenu a changé.
Lors de l’ajout d’un dépôt à l’environnement — Si .devin/blueprint.yaml existe sur la branche par défaut, le blueprint est automatiquement récupéré depuis Git lors de la détection initiale.
À chaque commit sur la branche par défaut (sur activation) — Pour les dépôts dont l’option Run on every commit to default branch est activée, chaque push sur la branche par défaut synchronise le blueprint et déclenche un build. Voir Synchroniser et builder à chaque commit sur la branche par défaut.

La synchronisation est idempotente : si le contenu du fichier n’a pas changé depuis la dernière synchronisation, aucune nouvelle version n’est créée.

Synchronisation et build à chaque commit sur la branche par défaut

Pour les repositories GitHub.com, vous pouvez activer la synchronisation et les builds automatiques plutôt que d’appeler l’API depuis la CI ou de cliquer sur Sync :

Accédez à Settings > Environment > Blueprints et cliquez sur le repository.
Ouvrez l’onglet Advanced.
Activez Run on every commit to default branch.

Une fois ce paramètre activé, chaque push sur la branche par défaut synchronise le blueprint adossé à Git et met en file d’attente un build du snapshot pour chaque plateforme. Si un commit plus récent arrive alors que le build d’un commit antérieur est encore en file d’attente, ce build en attente est annulé afin que seul le commit le plus récent soit construit ; les builds déjà démarrés vont jusqu’à leur terme. Si le blueprint du repository est en mode Database, le build utilise le blueprint enregistré dans Devin plutôt que le fichier issu du commit. Activez Report status checks for each commit pour afficher le résultat de chaque build sous forme de check run GitHub sur le commit.

L’onglet Advanced n’apparaît que pour les repositories GitHub.com, et uniquement lorsque cette option est disponible pour votre organisation. Pour les autres fournisseurs Git, ou lorsque le paramètre est désactivé, utilisez la synchronisation via l’API ou le bouton Sync.

Sync vs. build

Sync et build sont deux opérations distinctes :

Sync récupère la version la plus récente de .devin/blueprint.yaml depuis Git et enregistre une nouvelle version du blueprint.
Build crée une nouvelle image snapshot à partir des versions actuelles du blueprint.

Dans l’UI, le bouton de synchronisation exécute les deux étapes en une seule action. L’API les dissocie pour vous laisser un contrôle total : appelez d’abord sync, puis déclenchez un build.

Synchronisation via l’API

L’API snapshot-setup est en version bêta et est proposée sous /v3beta1/. Les chemins d’endpoint et les formats de requête/réponse peuvent changer avant le passage à l’API stable /v3/.

Si Run on every commit to default branch n’est pas disponible ou est désactivé pour votre repository, la méthode recommandée pour maintenir la synchronisation des blueprints consiste à appeler l’API après la fusion des modifications apportées à .devin/blueprint.yaml. Cela se fait généralement dans un pipeline CI/CD (p. ex., une étape post-fusion dans GitHub Actions).

Processus de bout en bout

Étape 1 : Synchroniser le blueprint

Récupérez la dernière version de .devin/blueprint.yaml depuis la branche par défaut :

curl -X POST https://api.devin.ai/v3beta1/organizations/{org_id}/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'

Réponse :

{"repo_name": "owner/repo"}

Le champ repo_name accepte owner/repo pour GitHub, ou une URL complète du service pour les autres plateformes d’hébergement (p. ex., https://gitlab.com/org/repo).

Étape 2 : Lancer un build

Après la synchronisation, lancez un build du snapshot pour appliquer le nouveau blueprint :

curl -X POST https://api.devin.ai/v3beta1/organizations/{org_id}/snapshot-setup/builds \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Réponse :

{
  "build_id": "sbj-abc123",
  "status": "pending",
  "trigger": "manual",
  "triggered_by_user_id": "user-abc123",
  "pinned": false,
  "started_at": null,
  "completed_at": null,
  "created_at": 1718000000,
  "updated_at": 1718000000
}

Étape 3 : Interroger périodiquement le statut du build (facultatif)

Si vous souhaitez attendre que le build se termine dans votre pipeline CI :

curl https://api.devin.ai/v3beta1/organizations/{org_id}/snapshot-setup/builds/{build_id} \
  -H "Authorization: Bearer $DEVIN_API_TOKEN"

Le champ status prend successivement les valeurs suivantes : pending → running → succeeded ou failed (ou cancelled). Un build partiel est signalé comme succeeded par l’API, car le snapshot est utilisable.

Synchronisation à l’échelle de l’entreprise

Pour les entreprises ayant plusieurs organisations qui partagent le même dépôt, il existe un endpoint au niveau de l’entreprise qui synchronise toutes les organisations connectées au dépôt :

curl -X POST https://api.devin.ai/v3beta1/enterprise/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'

La réponse inclut le nombre d’orgs synchronisées :

{"repo_name": "owner/repo", "org_count": 3}

Exemple : workflow GitHub Actions

Automatisez la synchronisation + le build à chaque push sur la branche par défaut qui modifie le fichier blueprint :

# .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/v3beta1/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/v3beta1/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/builds" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{}'

Vous avez besoin d’un utilisateur de service ou d’un jeton d’accès personnel disposant des autorisations d’écriture sur l’environnement. Enregistrez le jeton sous DEVIN_API_TOKEN et l’ID de votre org sous DEVIN_ORG_ID dans les secrets de votre dépôt.

Modification des blueprints adossés à Git

Lorsqu’un blueprint est adossé à Git, l’éditeur de l’interface utilisateur passe en lecture seule et n’autorise plus les enregistrements directs. Vous avez alors deux possibilités pour apporter des modifications :

Créer une PR depuis l’éditeur

Ouvrez l’éditeur de blueprint dans Settings > Environment > Blueprints
Modifiez le YAML dans l’éditeur
Cliquez sur Create PR
Devin ouvre une pull request sur votre dépôt pour mettre à jour .devin/blueprint.yaml
Vérifiez, approuvez et fusionnez la PR
La synchronisation suivante prend en compte la modification et déclenche un build

C’est utile pour effectuer des modifications rapides sans quitter l’UI de Devin.

Modifiez directement dans votre repository

Modifiez .devin/blueprint.yaml dans votre IDE ou chez votre fournisseur Git
Validez et poussez vers la branche par défaut (ou ouvrez une PR et fusionnez-la)
Déclenchez une synchronisation via l’API ou cliquez sur Sync dans l’UI (inutile si Run on every commit to default branch est activé)

Il s’agit du workflow standard pour les Teams qui gèrent l’infrastructure as code. Associez-le à une step de CI pour automatiser la synchronisation (voir Synchroniser via l’API), ou activez la synchronisation automatique lors des commits sur la branche par défaut.

Suggestions de Devin

Lorsque Devin propose une modification du blueprint pendant une session (p. ex., après avoir analysé votre projet), la suggestion est appliquée en ouvrant une PR visant .devin/blueprint.yaml, plutôt qu’en l’enregistrant directement dans la base de données. Vous examinez et fusionnez la PR comme toute autre modification de code.

Monorepos et espaces de travail

Pour les monorepos avec plusieurs packages, vous pouvez utiliser la directive includes pour définir des blueprints distincts pour chaque espace de travail. Chaque espace de travail dispose de son propre fichier .devin/blueprint.yaml dans son sous-répertoire.

Blueprint racine avec inclusions

Le fichier racine .devin/blueprint.yaml indique quels espaces de travail disposent de leurs propres blueprints :

# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

Blueprints des espaces de travail

Chaque espace de travail inclus possède son propre .devin/blueprint.yaml :

# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

knowledge:
  - name: lint
    contents: pnpm lint
  - name: test
    contents: pnpm test

# my-repo/packages/backend/.devin/blueprint.yaml
maintenance: |
  pip install -r requirements.txt

knowledge:
  - name: lint
    contents: ruff check .
  - name: test
    contents: pytest

Règles d’inclusion

Chaque entrée includes correspond à un chemin de sous-répertoire (p. ex. packages/frontend). Devin recherche .devin/blueprint.yaml dans ce répertoire.
Vous pouvez également utiliser le chemin complet : packages/frontend/.devin/blueprint.yaml.
Seul le blueprint racine peut contenir includes. Les inclusions imbriquées (c’est-à-dire un blueprint inclus qui déclare lui-même includes) ne sont pas autorisées.
Chaque chemin d’espace de travail ne peut apparaître qu’une seule fois dans includes.
Si un fichier inclus est absent du dépôt, l’espace de travail correspondant est considéré comme supprimé et son blueprint est supprimé.

Basculer entre le mode Git et le mode base de données

Basculer vers Git

Si vous avez un blueprint existant géré en base de données et souhaitez passer à Git :

Créez .devin/blueprint.yaml dans votre dépôt avec le contenu souhaité
Envoyez les modifications vers la branche par défaut
Dans l’éditeur de blueprint, cliquez sur le menu déroulant Source et sélectionnez votre fournisseur Git (p. ex., “GitHub”)
Devin synchronise le fichier depuis Git et bascule en mode adossé à Git

Passer en mode base de données

Si vous souhaitez cesser d’utiliser le mode adossé à Git et gérer le blueprint dans l’UI :

Dans l’éditeur de blueprint, cliquez sur le menu déroulant Source et sélectionnez Database
Le contenu actuel est conservé, mais les prochains push vers .devin/blueprint.yaml ne mettront plus le blueprint à jour
Vous pouvez désormais le modifier et l’enregistrer directement dans l’UI

Faire passer le blueprint racine en mode base de données fait également passer tous les blueprints d’espace de travail de ce dépôt en mode base de données, car la synchronisation s’effectue au niveau du dépôt.

Espaces de travail détachés

Vous pouvez détacher de Git des blueprints d’espace de travail individuels tout en conservant la racine en mode adossé à Git. Un espace de travail détaché est modifiable dans l’interface utilisateur et ignoré lors de la synchronisation. Cela est utile lorsqu’un espace de travail a besoin d’une dérogation temporaire sans affecter le reste du dépôt. Pour rattacher un espace de travail détaché, rebasculez sa source sur Git depuis le menu déroulant de la source.

Historique des versions

Chaque synchronisation crée une nouvelle version dans l’historique du blueprint, avec les informations suivantes :

Source : git_sync pour les versions créées par synchronisation, manual pour les versions créées dans l’UI
Commit SHA : le commit de la branche par défaut sur lequel la synchronisation a été effectuée (avec un lien vers le commit sur votre fournisseur Git)

Vous pouvez consulter l’historique complet des versions et les diffs dans l’onglet Version history de l’éditeur de blueprint.

YAML multidocument

Comme dans l’éditeur de l’UI, .devin/blueprint.yaml prend en charge le YAML multidocument avec le séparateur ---. Vous pouvez ainsi définir des configurations spécifiques à chaque plateforme dans un seul fichier :

# Configuration 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

Voir Support Windows pour plus de détails sur les blueprints multiplateformes.

Dépannage

Le blueprint ne se synchronise pas

Le fichier est-il au bon emplacement ? Il doit se trouver dans .devin/blueprint.yaml à la racine du repository (ou dans <workspace>/.devin/blueprint.yaml pour les espaces de travail inclus).
Avez-vous déclenché une synchronisation ? Par défaut, la synchronisation ne se fait pas automatiquement lors d’un push. Appelez l’endpoint API de synchronisation ou cliquez sur le bouton Sync dans l’interface utilisateur. Si vous attendez que les pushs déclenchent une synchronisation automatique, vérifiez que l’option Run on every commit to default branch est activée dans l’onglet Advanced du repository et que vous avez poussé sur la branche par défaut.
Le repository est-il dans l’environnement de Devin ? Le repository doit être ajouté dans Settings > Environment > Blueprints pour que la synchronisation puisse s’exécuter.
Le mode adossé à Git est-il activé ? Le blueprint doit être en mode adossé à Git (et non en mode base de données) pour que la synchronisation puisse le mettre à jour.

Erreurs liées à un YAML non valide

Si .devin/blueprint.yaml contient du YAML non valide ou n’est pas conforme au schéma du blueprint, la synchronisation échoue et renvoie une erreur. Corrigez le fichier dans la branche par défaut, puis relancez la synchronisation. L’éditeur de blueprint dans l’interface utilisateur valide le schéma et affiche les erreurs avant que vous ne créiez une PR, ce qui permet de détecter les problèmes avant qu’ils n’atteignent la branche par défaut.

Blueprint affiche “Database” après un push

Si vous avez poussé un .devin/blueprint.yaml mais que l’éditeur affiche toujours “Database” comme source, il se peut que le blueprint ne soit pas encore passé en mode adossé à Git. Utilisez le menu déroulant Source pour basculer vers votre fournisseur Git, ce qui déclenchera la synchronisation initiale.

​Vue d’ensemble

​Comment Devin choisit le mode lorsque vous ajoutez un repository

​Premiers pas

​1. Créer le fichier blueprint

​2. Pousser sur la branche par défaut

​3. Vérifiez dans l’UI

​Comment fonctionne la synchronisation

​Synchronisation et build à chaque commit sur la branche par défaut

​Sync vs. build

​Synchronisation via l’API

​Processus de bout en bout

​Étape 1 : Synchroniser le blueprint

​Étape 2 : Lancer un build

​Étape 3 : Interroger périodiquement le statut du build (facultatif)

​Synchronisation à l’échelle de l’entreprise

​Exemple : workflow GitHub Actions

​Modification des blueprints adossés à Git

​Créer une PR depuis l’éditeur

​Modifiez directement dans votre repository

​Suggestions de Devin

​Monorepos et espaces de travail

​Blueprint racine avec inclusions

​Blueprints des espaces de travail

​Règles d’inclusion

​Basculer entre le mode Git et le mode base de données

​Basculer vers Git

​Passer en mode base de données

​Espaces de travail détachés

​Historique des versions

​YAML multidocument

​Dépannage

​Le blueprint ne se synchronise pas

​Erreurs liées à un YAML non valide

​Blueprint affiche “Database” après un push

Vue d’ensemble

Comment Devin choisit le mode lorsque vous ajoutez un repository

Premiers pas

1. Créer le fichier blueprint

2. Pousser sur la branche par défaut

3. Vérifiez dans l’UI

Comment fonctionne la synchronisation

Synchronisation et build à chaque commit sur la branche par défaut

Sync vs. build

Synchronisation via l’API

Processus de bout en bout

Étape 1 : Synchroniser le blueprint

Étape 2 : Lancer un build

Étape 3 : Interroger périodiquement le statut du build (facultatif)

Synchronisation à l’échelle de l’entreprise

Exemple : workflow GitHub Actions

Modification des blueprints adossés à Git

Créer une PR depuis l’éditeur

Modifiez directement dans votre repository

Suggestions de Devin

Monorepos et espaces de travail

Blueprint racine avec inclusions

Blueprints des espaces de travail

Règles d’inclusion

Basculer entre le mode Git et le mode base de données

Basculer vers Git

Passer en mode base de données

Espaces de travail détachés

Historique des versions

YAML multidocument

Dépannage

Le blueprint ne se synchronise pas

Erreurs liées à un YAML non valide

Blueprint affiche “Database” après un push