> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Blueprints adossés à Git

> Stockez les blueprints dans .devin/blueprint.yaml de votre dépôt et synchronisez-les via l’API ou l’interface utilisateur.

<div id="overview">
  ## Vue d’ensemble
</div>

Les blueprints adossés à Git vous permettent de stocker la configuration de votre environnement directement dans votre dépôt 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                                                                                 |
| -------------------------------- | --------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Base de données (par défaut)** | L’interface Settings de Devin           | Modifier dans le navigateur            | Enregistré immédiatement au clic                                                                              |
| **Adossé à Git**                 | `.devin/blueprint.yaml` dans votre repo | 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 |

<Info>
  Les blueprints adossés à Git utilisent le même format YAML que l’éditeur de l’interface utilisateur. Consultez la [référence Blueprint](/fr/onboard-devin/environment/blueprint-reference) pour la spécification complète des champs.
</Info>

<div id="getting-started">
  ## Premiers pas
</div>

<div id="1-create-the-blueprint-file">
  ### 1. Créer le fichier blueprint
</div>

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 :

```yaml theme={null}
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
```

<div id="2-push-to-the-default-branch">
  ### 2. Pousser sur la branche par défaut
</div>

Validez puis poussez `.devin/blueprint.yaml` sur la branche par défaut de votre dépôt (généralement `main` ou `master`).

Si le dépôt 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. Si vous ajoutez le dépôt pour la première fois, lors de la détection initiale, Devin lit le blueprint depuis Git.

<div id="3-verify-in-the-ui">
  ### 3. Vérifiez dans l’UI
</div>

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é.

<div id="how-sync-works">
  ## Comment fonctionne la synchronisation
</div>

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. La synchronisation ne s'effectue **pas** automatiquement lors d'un push — vous devez la déclencher explicitement :

1. **Synchronisation via l'API** — Appelez l'endpoint de synchronisation v3 (voir [Synchronisation via l'API](#sync-via-the-api) ci-dessous). Il s'agit de l'approche recommandée pour les pipelines CI/CD.
2. **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é.
3. **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.

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.

<div id="sync-vs-build">
  ### Sync vs. build
</div>

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 v3 les dissocie pour vous laisser un contrôle total : appelez d’abord sync, puis déclenchez un build.

<div id="sync-via-the-api">
  ## Synchronisation via l’API
</div>

La méthode recommandée pour maintenir la synchronisation des blueprints consiste à appeler l’API v3 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).

<div id="end-to-end-flow">
  ### Processus de bout en bout
</div>

```mermaid theme={null}
sequenceDiagram
    participant Dev as Developer
    participant Git as Git Provider
    participant CI as CI/CD Pipeline
    participant API as Devin API
    Dev->>Git: Push/merge .devin/blueprint.yaml
    Git->>CI: Trigger post-merge workflow
    CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/sync
    API-->>CI: 200 OK (repo_name)
    CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/builds
    API-->>CI: 201 Created (build_id, status)
    CI->>API: GET /v3/organizations/{org_id}/snapshot-setup/builds/{build_id}
    API-->>CI: 200 OK (status: succeeded)
```

<div id="step-1-sync-the-blueprint">
  ### Étape 1 : Synchroniser le blueprint
</div>

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

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

Réponse :

```json theme={null}
{"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`).

<div id="step-2-trigger-a-build">
  ### Étape 2 : Lancer un build
</div>

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

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

Réponse :

```json theme={null}
{
  "build_id": "sbj-abc123",
  "status": "running",
  "trigger": "api",
  "created_at": 1718000000,
  "updated_at": 1718000000
}
```

<div id="step-3-poll-build-status-optional">
  ### Étape 3 : Interroger périodiquement le statut du build (facultatif)
</div>

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

```bash theme={null}
curl https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds/{build_id} \
  -H "Authorization: Bearer $DEVIN_API_TOKEN"
```

Le champ `status` prend successivement les valeurs suivantes : `running` → `succeeded` ou `failed`.

<div id="enterprise-wide-sync">
  ### Synchronisation à l’échelle de l’entreprise
</div>

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 :

```bash theme={null}
curl -X POST https://api.devin.ai/v3/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 :

```json theme={null}
{"repo_name": "owner/repo", "org_count": 3}
```

<div id="example-github-actions-workflow">
  ### Exemple : workflow GitHub Actions
</div>

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

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

<Info>
  Vous avez besoin d’un [utilisateur de service](/fr/api-reference/overview) 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.
</Info>

<div id="editing-git-backed-blueprints">
  ## Modification des blueprints adossés à Git
</div>

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 :

<div id="create-a-pr-from-the-editor">
  ### Créer une PR depuis l’éditeur
</div>

1. Ouvrez l’éditeur de blueprint dans **Settings > Environment > Blueprints**
2. Modifiez le YAML dans l’éditeur
3. Cliquez sur **Create PR**
4. Devin ouvre une pull request sur votre dépôt pour mettre à jour `.devin/blueprint.yaml`
5. Vérifiez, approuvez et fusionnez la PR
6. 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.

<div id="edit-directly-in-your-repository">
  ### Modifiez directement dans votre dépôt
</div>

1. Modifiez `.devin/blueprint.yaml` dans votre IDE ou chez votre fournisseur Git
2. Validez et poussez vers la branche par défaut (ou ouvrez une PR et fusionnez-la)
3. Déclenchez une synchronisation via l’API ou cliquez sur Sync dans l’UI

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](#sync-via-the-api)).

<div id="devin-suggestions">
  ### Suggestions de Devin
</div>

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.

<div id="monorepos-and-workspaces">
  ## Monorepos et espaces de travail
</div>

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.

<div id="root-blueprint-with-includes">
  ### Blueprint racine avec inclusions
</div>

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

```yaml theme={null}
# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install
```

<div id="workspace-blueprints">
  ### Blueprints des espaces de travail
</div>

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

```yaml theme={null}
# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

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

```yaml theme={null}
# my-repo/packages/backend/.devin/blueprint.yaml
maintenance: |
  pip install -r requirements.txt

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

<div id="include-rules">
  ### Règles d’inclusion
</div>

* 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é.

<div id="switching-between-git-and-database-modes">
  ## Basculer entre le mode Git et le mode base de données
</div>

<div id="switch-to-git">
  ### Basculer vers Git
</div>

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

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

<div id="switch-to-database">
  ### Passer en mode base de données
</div>

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

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

<Warning>
  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.
</Warning>

<div id="detached-workspaces">
  ### Espaces de travail détachés
</div>

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.

<div id="version-history">
  ## Historique des versions
</div>

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.

<div id="multi-document-yaml">
  ## YAML multidocument
</div>

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 :

```yaml theme={null}
# 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](/fr/onboard-devin/environment/windows-support) pour plus de détails sur les blueprints multiplateformes.

<div id="troubleshooting">
  ## Dépannage
</div>

<div id="blueprint-not-syncing">
  ### Le blueprint ne se synchronise pas
</div>

* **Le fichier est-il au bon emplacement ?** Il doit se trouver dans `.devin/blueprint.yaml` à la racine du dépôt (ou dans `<workspace>/.devin/blueprint.yaml` pour les espaces de travail inclus).
* **Avez-vous déclenché une synchronisation ?** 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.
* **Le dépôt est-il dans l'environnement de Devin ?** Le dépôt 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.

<div id="invalid-yaml-errors">
  ### Erreurs liées à un YAML non valide
</div>

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.

<div id="blueprint-shows-database-after-pushing">
  ### Blueprint affiche "Database" après un push
</div>

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.