> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration déclarative
> Définissez votre environnement dans des blueprints YAML. Les builds s’exécutent automatiquement pour produire des snapshots à partir desquels chaque session s’initialise.
## Premiers pas
**Prérequis** : Devin doit avoir accès à vos dépôts avant que vous puissiez configurer son environnement. Si vous n’avez pas encore configuré votre intégration Git, consultez [Avant de commencer](/fr/onboard-devin/environment#before-you-start) pour suivre les étapes de configuration. Les utilisateurs Enterprise doivent également accorder à chaque org l’accès à ses dépôts dans **Enterprise Settings > Repository Permissions**.
**Vous utilisez encore la configuration classique ?** Vous pouvez migrer vers la configuration déclarative à tout moment. Devin peut prendre en charge l’essentiel de la migration pour vous. Consultez [Migrer vers la configuration déclarative](/fr/onboard-devin/environment/migration).
Idéal pour la plupart des utilisateurs. Devin analyse votre projet, identifie les outils et dépendances nécessaires, puis génère le blueprint pour vous. Il ne vous reste plus qu’à le vérifier et l’approuver.
Ouvrez une nouvelle session et demandez à Devin de configurer le dépôt. Par exemple : *"Configure ton environnement pour ce repo."*
Devin propose un blueprint. Vous verrez des **cartes de suggestion** dans votre timeline. Vérifiez-les, puis cliquez sur **Approve**.
Une fois le build terminé, démarrez une nouvelle session. Devin démarre à partir du nouveau snapshot avec tout préconfiguré. Essayez de demander à Devin d’exécuter vos commandes de lint ou de test pour confirmer que tout fonctionne.
Idéal si vous savez exactement ce dont votre environnement a besoin ou si vous voulez garder un contrôle total sur chaque étape. C’est aussi plus rapide si vos commandes sont déjà prêtes.
Accédez à **Settings > Environment > Blueprints** dans la barre latérale de votre organisation.
Si vous ne voyez pas cette option, votre organisation utilise peut-être encore la configuration classique. Consultez [Migrer vers la configuration déclarative](/fr/onboard-devin/environment/migration) pour commencer.
Cliquez sur **Add** dans la section Repositories. Sélectionnez les dépôts avec lesquels vous voulez que Devin travaille, puis confirmez.
Les dépôts ajoutés ici sont clonés dans l’environnement de Devin lors de chaque build. Vous pouvez en ajouter d’autres à tout moment.
Cliquez sur un dépôt pour ouvrir son éditeur de blueprint. Voici un exemple simple :
```yaml theme={null}
initialize: |
curl -LsSf https://astral.sh/uv/install.sh | sh
maintenance: |
uv sync
knowledge:
- name: lint
contents: uv run ruff check .
- name: test
contents: uv run pytest
```
Pour plus de langages et de patterns, consultez la [bibliothèque de modèle](/fr/onboard-devin/environment/templates).
Cliquez sur **Save**. Un build démarre automatiquement (généralement en 2 à 10 minutes). Suivez sa progression depuis **Settings > Environment > Snapshots**, sous **Current build**.
Une fois que le build affiche **Success**, démarrez une nouvelle session Devin. Devin démarre à partir du nouveau snapshot avec tout préconfiguré. Essayez de demander à Devin d’exécuter vos commandes de lint ou de test pour vérifier que l’environnement fonctionne.
La suite de ce guide détaille le parcours manuel. Elle est également utile pour comprendre ce que Devin a généré si vous avez utilisé le parcours recommandé.
## Comment ça marche
La configuration déclarative repose sur trois concepts :
| Concept | Ce que c’est | Analogie |
| ------------- | -------------------------------------------------------------------------------------------------------- | -------------- |
| **Blueprint** | Une configuration YAML qui décrit ce qu’il faut installer et comment configurer l’environnement de Devin | Dockerfile |
| **Build** | Le processus qui exécute votre blueprint, clone les repos et produit un snapshot | `docker build` |
| **Snapshot** | Une image figée et amorçable de l’environnement à partir de laquelle les sessions démarrent | Docker image |
**Les blueprints décrivent ce que vous voulez.** Vous les rédigez et les modifiez dans l’interface Settings.
**Les builds exécutent vos blueprints pour produire des snapshots.** Les builds se lancent automatiquement lorsque vous enregistrez un blueprint, puis périodiquement (\~toutes les 24 heures) afin de maintenir les dépendances à jour.
**Les snapshots sont la base à partir de laquelle les sessions démarrent.** Chaque organisation dispose d’un snapshot actif. Chaque session démarre à partir d’une copie neuve. Les modifications apportées pendant une session ne sont pas répercutées dans le snapshot.
### Sections du blueprint
Un blueprint comporte trois sections, plus un bloc `clone` facultatif pour les blueprints au niveau du dépôt :
| Section | Objectif | Quand elle s’exécute |
| ------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `initialize` | Installer les outils, les environnements d’exécution, les packages système | Pendant les builds uniquement. Les résultats sont enregistrés dans le snapshot. |
| `maintenance` | Installer/mettre à jour les dépendances du projet, écrire les configurations d’authentification | Pendant les builds. Présentée à l’agent au démarrage de la session (non exécutée automatiquement). |
| `knowledge` | Informations de référence pour Devin (commandes de lint, test et build) | Non exécutée. Chargée dans le contexte de Devin au démarrage de la session. |
| `clone` | Remplacer les paramètres git-clone par défaut pour le dépôt (niveau dépôt uniquement) | Appliquée pendant l’étape de clonage du build. |
**`initialize`** sert à ce qui ne doit se produire qu’une seule fois : environnements d’exécution, packages système, outils CLI globaux.
**`maintenance`** sert à l’installation des dépendances qui doivent rester à jour. Elle s’exécute pendant les builds et est présentée à l’agent au démarrage de la session afin qu’il puisse les relancer si les dépendances ont changé (p. ex. après récupération du code le plus récent). Les commandes ne sont pas exécutées automatiquement au démarrage de la session, mais doivent tout de même être rapides et incrémentales (utilisez `npm install`, pas `npm ci`).
**`knowledge`** contient des informations de référence et n’est pas exécutée. C’est ainsi que vous indiquez à Devin les bonnes commandes de lint, de test et de build. Gardez des entrées légères et axées sur des commandes exécutables.
**`clone`** (niveau dépôt uniquement) remplace les paramètres par défaut que Devin utilise pour cloner le dépôt dans le snapshot — par exemple, extraire une branche autre que la branche par défaut (`ref`), modifier la destination du clone (`path`) ou ignorer les sous-modules ou les objets LFS. Chaque champ est facultatif. Consultez [référence Blueprint → clone](/fr/onboard-devin/environment/blueprint-reference#clone) pour la liste complète des champs.
**Knowledge ici vs la fonctionnalité produit Knowledge :** La section `knowledge` de votre blueprint sert à de courtes références de commandes liées à l’environnement. Pour la documentation d’architecture, les conventions et les workflows d’équipe, utilisez plutôt la fonctionnalité autonome [Knowledge](/fr/product-guides/knowledge).
**YAML multi-document :** L’éditeur de blueprint prend en charge le YAML multi-document à l’aide du séparateur `---`. Cela vous permet d’organiser des blueprints complexes en sections logiques dans un seul éditeur.
Pour la spécification complète des champs (types d’étapes, variables d’environnement, secrets et fichiers joints), consultez la [référence Blueprint](/fr/onboard-devin/environment/blueprint-reference).
### Périmètre des blueprints
Vous pouvez définir des blueprints à deux niveaux :
| Niveau | Où configurer | Que mettre ici |
| ---------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Organisation** | Settings > Environment > Blueprints > Configuration à l’échelle de l’organisation | Outils partagés par tous les dépôts : environnements d’exécution, gestionnaires de paquets, authentification Docker |
| **Dépôt** | Settings > Environment > Blueprints > \[nom du dépôt] | Configuration spécifique au projet : `npm install`, commandes de lint/test/build |
Les blueprints sont **additifs** : les blueprints de dépôt s’appuient sur le blueprint de l’organisation. L’étape `maintenance` d’un dépôt peut utiliser des outils installés par l’étape `initialize` de l’organisation. Si un seul dépôt a besoin d’un outil, placez-le dans le blueprint de ce dépôt. Si tous les dépôts en ont besoin, placez-le dans le blueprint de l’organisation.
**Utilisateurs Enterprise :** Il existe un troisième niveau, le blueprint Enterprise, qui s’applique à toutes les organisations. Consultez [la vue d’ensemble de l’environnement Enterprise](/fr/enterprise/environment-management/overview) pour plus de
détails.
## Builds et sessions
### Le snapshot
Votre organisation dispose d’**un snapshot actif** : une image de machine virtuelle avec vos outils, dépôts et dépendances préinstallés. Tous les dépôts configurés sont clonés et configurés dans cette image unique. Chaque session démarre à partir d’une nouvelle copie.
### Comment fonctionnent les builds
Un build crée un nouveau snapshot en exécutant vos blueprints dans l’ordre :
```
1. Enterprise blueprint, if configured (runs in ~):
a. initialize
b. maintenance
2. Org blueprint (runs in ~):
a. initialize
b. maintenance
3. Cloner tous les dépôts (jusqu'à 10 en simultané).
Le blueprint de chaque repo peut remplacer les paramètres de clonage par défaut via le
bloc `clone` (branche/tag, profondeur, sous-modules, LFS, etc.).
4. For each configured repo, in the order shown in Settings
(runs in ~/repos/):
a. initialize
b. maintenance
5. Health check, then snapshot is saved
```
Les couches sont **cumulatives** : les commandes propres au dépôt peuvent utiliser des outils installés par l’organisation ou le blueprint Enterprise. Les niveaux inférieurs ne peuvent pas écraser ce qu’un niveau supérieur a configuré. Les builds prennent généralement 5 à 15 minutes. Chaque étape expire au bout d’1 heure.
### Fonctionnement des sessions
Chaque session démarre avec une **nouvelle copie** du snapshot. Lorsque la session se termine, toutes les modifications sont abandonnées. Au démarrage de la session :
1. La version la plus récente du code est récupérée pour le ou les repos concernés.
2. Les commandes `maintenance` (Enterprise, organisation et repo) sont présentées à l’agent comme contexte — **elles ne sont pas exécutées automatiquement**. L’agent peut les relancer s’il détecte que les dépendances ont changé depuis le dernier build.
3. Les entrées `Knowledge` de ce repo sont chargées dans le contexte de Devin.
**Knowledge est spécifique à chaque repo.** Si vous avez 5 repos configurés, Devin ne voit que les entrées Knowledge de celui sur lequel il travaille.
### Ce qui déclenche un build
| Déclencheur | Description |
| ------------------------------- | ----------------------------------------------------------------- |
| Enregistrement d'un blueprint | Création, mise à jour ou suppression d'un blueprint |
| Ajout ou suppression d'un dépôt | Toute modification de la liste des dépôts |
| Ajout d'un secret de dépôt | Les nouveaux secrets nécessitent un rebuild pour être disponibles |
| Déclenchement manuel | Clic sur **Build snapshot** dans l'interface |
| Actualisation périodique | Automatique, environ toutes les 24 heures |
| Suggestion de Devin | Devin propose une modification du blueprint pendant une session |
Un seul build peut s'exécuter à la fois. Tout nouveau déclencheur annule tout build en file d'attente et relance le processus à zéro.
### États des builds
| Status | Meaning |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Success** | Toutes les étapes sont terminées. Le snapshot est prêt. |
| **Partial** | Certaines étapes au niveau du repo ont échoué, mais le snapshot reste utilisable. Les repos qui ont réussi fonctionnent normalement ; les repos en échec nécessitent de corriger leurs blueprints. |
| **Failed** | Échec critique (la configuration de l’organisation ou de l’environnement Enterprise a échoué). Le snapshot n’est pas utilisable. |
| **Cancelled** | Remplacé par un build plus récent ou annulé manuellement. |
Un build **partial** produit quand même un snapshot exploitable. Si l’un des cinq repos a un blueprint défectueux, les quatre autres sont entièrement fonctionnels.
**Le build échoue ?** Consultez [Résolution des problèmes de build](#troubleshooting-builds) pour obtenir un guide de débogage pas à pas.
## Gérer votre environnement
### États des dépôts
Les dépôts apparaissent sous trois états dans les paramètres d’Environment :
| État | Signification |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| **Configured** | Dispose d’un blueprint avec initialize/maintenance/knowledge. Entièrement configuré dans le snapshot. |
| **Included** | Cloné dans le snapshot, mais sans blueprint personnalisé. Devin peut accéder au code. |
| **Available** | Connecté à l’organisation, mais non ajouté à l’environnement. Non cloné. |
**Included vs. configured :** Un dépôt « included » est cloné pour que Devin puisse accéder au code, mais il n’a pas de commandes de configuration personnalisées. Un dépôt « configured » comporte des instructions explicites pour initialize/maintenance/knowledge.
### Secrets
Faites référence aux secrets avec la syntaxe `$VARIABLE_NAME`. Ajoutez-les dans l’onglet **Secrets** de l’éditeur de blueprint.
```yaml theme={null}
maintenance:
- name: Configure private registry
run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
```
Les secrets sont disponibles sous forme de variables d’environnement lors des builds et des sessions. Ils sont supprimés avant que le snapshot ne soit enregistré, mais si une commande écrit la valeur d’un secret dans un fichier de configuration pendant `initialize`, cette valeur persiste dans le snapshot. Placez les étapes qui écrivent des identifiants dans `maintenance` afin qu’elles soient actualisées lors des builds périodiques.
Pour en savoir plus sur les périmètres des secrets et leur comportement, consultez la [référence Blueprint](/fr/onboard-devin/environment/blueprint-reference#environment-variables-and-secrets).
### Plusieurs dépôts
Chaque dépôt dispose de son propre blueprint. Lors d’un build, tous les dépôts sont configurés dans le même snapshot, puis clonés dans des répertoires distincts, avec des dépendances installées indépendamment.
Si deux dépôts installent des versions différentes d’un outil global ou modifient des fichiers partagés (comme `~/.bashrc`), c’est le dernier à s’exécuter qui l’emporte. Installez les outils partagés dans le blueprint à l’échelle de l’organisation afin d’éviter les conflits.
### GitHub Actions
Au lieu d’écrire des scripts shell pour installer des outils et des environnements d’exécution, vous pouvez faire directement référence à des GitHub Actions dans votre blueprint. Devin télécharge et exécute l’action pendant le build, de la même manière que les runners CI de GitHub exécutent les étapes de l’action.
```yaml theme={null}
initialize:
- name: Install Python 3.12
uses: github.com/actions/setup-python@v5
with:
python-version: "3.12"
```
C'est particulièrement utile pour les actions de configuration de langage comme `setup-python`, `setup-node` et `setup-go`, qui gèrent automatiquement les versions et la configuration du PATH.
Pour plus de détails sur la syntaxe, des exemples et les limites, consultez [GitHub Actions dans les blueprints](/fr/onboard-devin/environment/github-actions).
### Monorepos
Vous pouvez exécuter des commandes dans des sous-répertoires à l’aide de subshells, ou créer des blueprints dédiés au périmètre d’un espace de travail pour des packages individuels. Devin prend également en charge des entrées Knowledge par package afin que chaque espace de travail dispose de ses propres commandes de lint, de test et de build.
Voir [Workspaces and monorepos](/fr/onboard-devin/environment/workspaces) pour les instructions de configuration et des exemples.
### Épinglage et mises à jour automatiques
Par défaut, Devin utilise le snapshot du dernier build réussi. L’**épinglage** permet de verrouiller le snapshot d’un build spécifique. C’est utile lorsqu’un nouveau build introduit une régression, ou lorsque vous souhaitez figer l’environnement pour un lot de sessions.
**Pour épingler :** accédez à **Settings > Environment > Snapshots**, recherchez le build dans l’historique (il doit être `success` ou `partial` et dater de moins de 7 jours), puis cliquez sur **Épingler**. Une fois épinglé, les actualisations périodiques sont suspendues et l’interface affiche **Mises à jour automatiques en pause**.
**Pour retirer l’épinglage :** cliquez sur **Reprendre les mises à jour automatiques**. Devin bascule vers le dernier build réussi.
### Blueprints versionnés avec Git
Vous pouvez stocker des blueprints directement dans votre dépôt sous forme de fichiers `.devin/blueprint.yaml`. Après avoir fusionné les modifications, appelez l'API de synchronisation (ou cliquez sur Sync dans l'UI) pour mettre à jour le blueprint, puis déclenchez un build. Vous bénéficiez ainsi du même workflow de revue de code que pour le code de votre application, avec une synchronisation automatisée via une étape de CI.
Voir [Blueprints versionnés avec Git](/fr/onboard-devin/environment/git-backed-blueprints) pour les instructions de configuration et plus de détails.
## Résolution des problèmes de build
### Échec de l’étape d’initialisation
**Causes fréquentes :** faute de frappe dans une commande shell, package indisponible, délai d’attente réseau dépassé, référence GitHub Action incorrecte.
**Correctif :** consultez les logs de build pour connaître l’erreur exacte. Mettez à jour `initialize` dans votre blueprint et enregistrez. Un nouveau build est automatiquement activé.
### Échec du clonage du repo
**Causes fréquentes :** Devin n'a pas accès au repo, le repo a été renommé/déplacé/supprimé, ou il s'agit d'un problème réseau temporaire.
**Correctif :** Vérifiez l'accès au repo dans les paramètres de votre service Git. Supprimez le repo, puis ajoutez-le à nouveau s'il a été renommé.
### L’étape de maintenance a échoué
**Causes courantes :** conflit de dépendances, bibliothèque système manquante, espace disque insuffisant, fichier de verrouillage non synchronisé.
**Correctif :** vérifiez les logs du package ou de la commande qui échoue. Mettez à jour `maintenance` ou `initialize` pour installer les dépendances manquantes, ou corrigez le fichier de verrouillage dans votre dépôt.
### Expiration du build
Chaque étape a un délai d’expiration d’une heure. Causes fréquentes : compilation de dépendances natives volumineuses à partir du code source (utilisez des binaires précompilés), téléchargement d’artefacts volumineux, commandes qui se bloquent en attendant une saisie (toutes les commandes doivent être non interactives).
### Itérer sur les correctifs
1. Consultez les logs de build pour identifier la cause de l'échec
2. Mettez à jour le blueprint concerné
3. Enregistrez (un nouveau build s'active automatiquement)
4. Surveillez les logs du nouveau build
5. Répétez jusqu'à ce que le build se termine avec succès
Vous n'avez pas besoin d'attendre la fin d'un build en échec. L'enregistrement d'une nouvelle configuration annule tout build en file d'attente et relance un build à partir de zéro.
## Prochaines étapes
Accélérez les builds en ne reconstruisant que les espaces de travail dont les blueprints ont changé.
Utilisez GitHub Actions pour installer des langages, des outils et des SDK sans écrire de scripts shell.
Subshells, périmètres des espaces de travail et entrées Knowledge pour les dépôts multipackages.
Référence complète des champs : types d’étapes, variables d’environnement, secrets, fichiers joints.
Blueprints prêts à copier-coller pour Python, Node.js, Go, Java, Ruby, Rust et cas d’usage avancés.
Stockez les blueprints dans votre dépôt sous `.devin/blueprint.yaml` et synchronisez-les via l’API ou l’UI.
Guide étape par étape pour passer de l’assistant interactif aux blueprints déclaratifs.
Gestion des environnements à l’échelle de l’entreprise : hiérarchie à 3 niveaux, secrets et configuration entre organisations.