docs: documenter la gestion des dépôts GitLab par la console

docs/guide/repositories-management.md

@@ -26,6 +26,19 @@ Cliquer enfin sur le bouton `Ajouter le dépôt`.
 
 > Cette opération demande d'attendre jusqu'à quelques minutes.
 
+## Cohérence et nettoyage des dépôts (reprovisionnement)
+
+À chaque opération de **reprovisionnement du projet** (bouton *Reprovisionner le projet* de la [page projet](/guide/projects-management)), la console compare les dépôts présents sur le GitLab de la plateforme avec ceux déclarés dans le projet, puis supprime les dépôts non conformes. Ce comportement s'applique aux dépôts gérés par la plateforme (portant le marqueur `plugin-managed`).
+
+Pour l'utilisateur, cela signifie :
+
+- **Créer un dépôt via la console** est la seule voie sûre. Un dépôt créé manuellement dans le GitLab de la plateforme peut être supprimé lors du prochain reprovisionnement s'il est considéré comme non conforme (porteur du marqueur de gestion et absent de la liste des dépôts du projet).
+- **Supprimer un dépôt dans la console** supprime effectivement le dépôt correspondant dans le GitLab de la plateforme lors de la prochaine synchronisation. La suppression GitLab étant asynchrone, un reprovisionnement lancé juste après peut afficher un message transitoire de type `already marked for deletion` ; il est ignoré et n'interrompt plus l'opération.
+- **Certains dépôts techniques sont protégés** et ne sont jamais supprimés, même s'ils n'apparaissent pas dans la liste des dépôts du projet : le dépôt `mirror` (synchronisation des dépôts externes), le dépôt `infra-apps` (dépôt d'infrastructure) et, selon les plugins activés, les dépôts techniques associés (par exemple le dépôt d'observabilité). Ils sont recréés automatiquement si besoin.
+- Un dépôt créé manuellement dans le GitLab de la plateforme **sans** marqueur de gestion n'est pas modifié par la console, mais il n'est pas non plus intégré aux chaînes de construction et de déploiement du projet.
+
+> En cas de doute, créez, modifiez et supprimez vos dépôts uniquement depuis la console, et relancez un reprovisionnement si un dépôt apparaît manquant après une suppression.
+
 Lorsqu'un dépôt est créé dans la console en tant que `dépôt d'infrastructure`, la plateforme créée automatiquement l'application [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) associée qui permettra le déploiement.
 
 > Des exemples de dépôts sont disponibles dans la section [tutoriels](tutorials).

docs/services/gitlab.md

@@ -66,6 +66,50 @@ Suivant les principes *GitOps*, les déploiements sur l'orchestrateur du contene
 
 Ces dépôts sources sont utilisés par ArgoCD afin de déployer l'infrastructure applictive sur Kubernetes. Votre application est déployé dans un namespace dédié au projet et automatiquement provisionné par la console de la plateforme Cloud π Native.
 
+## Gestion des ressources GitLab par la Console
+
+La Console Cloud π Native pilote l'ensemble des ressources GitLab créées dans
+le groupe du projet (`<NOM_ORGANISATION>/<NOM_PROJET>`) lors de chaque
+**provisionnement** et **reprovisionnement**. Elle maintient un état de
+cohérence : les dépôts présents sur le GitLab interne sont comparés à ceux
+déclarés dans la Console, et les dépôts non conformes sont supprimés.
+
+### Dépôts gérés et marqueurs
+
+Chaque dépôt créé par la Console porte un **topic GitLab** (`plugin-managed`)
+qui le distingue des dépôts créés manuellement :
+
+- **Dépôts applicatifs et d'infrastructure** déclarés dans la Console : créés
+  dans le groupe du projet, marqués `plugin-managed`, et synchronisés avec le
+  dépôt externe via le dépôt `mirror`.
+- **Dépôts techniques** (dits *system managed*) : créés automatiquement par la
+  Console et porteurs du topic `system-managed`. Ils ne figurent jamais dans la
+  liste des dépôts déclarés du projet et sont **protégés** de toute suppression
+  lors de la réconciliation. On y trouve :
+  - le dépôt `mirror` : pilote la synchronisation des dépôts externes ;
+  - le dépôt `infra-apps` : dépôt d'infrastructure du projet ;
+  - les dépôts techniques associés aux plugins activés (par exemple le dépôt
+    d'observabilité).
+
+### Réconciliation et purge
+
+À chaque reprovisionnement, la Console :
+
+1. recrée ou met à jour les dépôts techniques (`system-managed`) ;
+2. crée ou met à jour les dépôts déclarés (`plugin-managed`) ;
+3. **supprime** les dépôts portant `plugin-managed` qui ne sont plus déclarés
+   dans le projet (dépôt supprimé dans la Console, par exemple).
+
+Un dépôt créé manuellement dans le GitLab interne **sans** marqueur de gestion
+n'est pas modifié par la Console, mais n'est pas non plus intégré aux chaînes
+de construction et de déploiement. Il est recommandé de toujours passer par la
+Console pour créer, modifier et supprimer les dépôts d'un projet.
+
+> La suppression d'un dépôt sur le GitLab interne est asynchrone. Si un
+> reprovisionnement est lancé alors qu'une suppression est déjà en cours, la
+> Console ignore l'erreur transitoire `already marked for deletion` et poursuit
+> la réconciliation.
+
 ## Schéma de fonctionnement
 Le schéma ci-dessous présente le fonctionnement général :