shikanime · Oct 14, 2026 · Oct 14, 2026
diff --git a/docs/.vitepress/sidebar.json b/docs/.vitepress/sidebar.json
@@ -144,6 +144,10 @@
           {
             "text": "Grafana",
             "link": "/guide/rbac/grafana"
+          },
+          {
+            "text": "GitLab",
+            "link": "/guide/rbac/gitlab"
           }
         ]
       },

diff --git a/docs/administration/roles.md b/docs/administration/roles.md
@@ -31,58 +31,8 @@ L’onglet `Membres` permet d’ajouter ou retirer des utilisateurs.
 
 ![Membres d’un rôle plateforme](/img/iam/admin-role-members.png)
 
-## Effet sur les services intégrés (exemple GitLab)
-
-La Console est la source de vérité des rôles et permissions. Selon les intégrations actives et le niveau de synchronisation, ces droits peuvent être projetés vers des services externes.
-
-À ce jour, GitLab est le service intégré pour ce contrôle.
-
-Vérifier les points suivants :
-
-- l’intégration du service concerné est active ;
-- le mapping des groupes/rôles est configuré pour ce service ;
-- la synchronisation est terminée.
-
-### Correspondance Console → GitLab (par défaut)
-
-La correspondance ci-dessous reflète la configuration par défaut. Elle peut être adaptée via la configuration du plugin GitLab.
-
-Rôles plateforme (scope Console) :
-
-| Rôle Console (groupe OIDC) | Droits GitLab |
-| --- | --- |
-| `/console/admin` | Administrateur GitLab |
-| `/console/readonly` | Auditeur GitLab |
-
-Rôles projet (scope projet) :
-
-| Rôle Console (groupe OIDC) | Droits GitLab sur le groupe du projet |
-| --- | --- |
-| `/<projectSlug>/console/admin` | Maintainer |
-| `/<projectSlug>/console/devops` | Developer |
-| `/<projectSlug>/console/developer` | Developer |
-| `/<projectSlug>/console/readonly` | Reporter |
-| Propriétaire du projet (Console) | Owner |
-
-Paramètres de configuration utiles (plugin GitLab) :
-
-| Clé | Rôle |
-| --- | --- |
-| `adminGroupPath` | Groupe OIDC donnant les droits d’administrateur GitLab |
-| `auditorGroupPath` | Groupe OIDC donnant les droits d’auditeur GitLab |
-| `projectMaintainerGroupPathSuffix` | Suffixe OIDC donnant l’accès Maintainer |
-| `projectDeveloperGroupPathSuffix` | Suffixe OIDC donnant l’accès Developer |
-| `projectReporterGroupPathSuffix` | Suffixe OIDC donnant l'accès Reporter |
-
-:::warning
-**Phase de rétrocompatibilité (9.16.x)** — **GitLab** attribue toujours le rôle `Développeur` par défaut lors de l'ajout d'un membre. Le rôle `Lecture seule` de la Console (`/console/readonly`, normalement dédié aux personnes chargés de faire des rapports ou des audits) n'a donc aucun effet sur **Gitlab**. Ce comportement est conservé temporairement pour compatibilité ; Il évoluera vers le rôle **Gitlab** `Invité` dans une prochaine version.
-:::
-
-:::danger
-**Changement cassant** — Les rôles sont désormais provisionnés de manière autoritaire dans les services intégrés (GitLab). La Console prend le contrôle total de l'appartenance : tout membre non tracé par la Console sera **supprimé**, et seuls les membres assignés via les rôles Console seront **ajoutés**. Ce comportement empêche toute dérive entre la Console et les services externes. Les modifications manuelles de membership dans GitLab seront écrasées lors de la synchronisation.
-:::
-
 ## Voir aussi
 
+- [Groupes Keycloak et GitLab](/guide/rbac/gitlab)
 - [Gestion des rôles (projet)](/guide/roles)
 - [Utilisateurs](/administration/utilisateurs)
diff --git a/docs/guide/rbac/gitlab.md b/docs/guide/rbac/gitlab.md
@@ -0,0 +1,60 @@
+# Groupes Keycloak et GitLab
+
+Ce document décrit comment la Console propage les **groupes Keycloak** en **niveaux d'accès GitLab** (membres du groupe du projet), et quels droits en résultent.
+
+## Vue par rôle
+
+Ce que chaque rôle Console obtient réellement dans GitLab :
+
+| Rôle Console          | Groupe Keycloak             | Accès obtenu dans GitLab     |
+| --------------------- | --------------------------- | ---------------------------- |
+| Propriétaire projet  | —                           | **Owner** sur le groupe      |
+| Administrateur projet | `/<slug>/console/admin`     | **Maintainer** sur le groupe |
+| DevOps                | `/<slug>/console/devops`    | **Maintainer** sur le groupe |
+| Développeur           | `/<slug>/console/developer` | **Developer** sur le groupe  |
+| Lecture seule         | `/<slug>/console/readonly`  | **Reporter** sur le groupe   |
+| Security              | `/<slug>/console/security`  | **Reporter** sur le groupe   |
+| Admin plateforme      | `/console/admin`            | **Admin GitLab** (flag instance) |
+| Audit plateforme      | `/console/readonly`, `/console/security` | **Auditeur GitLab** (flag auditor) |
+
+## 1. Authentification : GitLab via OIDC Keycloak
+
+- GitLab est fédéré au fournisseur OIDC Keycloak ; les utilisateurs se connectent sans mot de passe local.
+- La Console approvisionne, pour chaque projet, le **groupe GitLab** et y ajoute les membres avec un niveau d'accès (Owner / Maintainer / Developer / Reporter / Guest).
+
+## 2. Groupes Keycloak et niveau GitLab résultant
+
+| Groupe Keycloak             | Niveau GitLab   |
+| --------------------------- | --------------- |
+| `/<slug>/console/admin`     | **Maintainer**  |
+| `/<slug>/console/devops`    | **Maintainer**  |
+| `/<slug>/console/developer` | **Developer**   |
+| `/<slug>/console/readonly`  | **Reporter**    |
+| `/<slug>/console/security`  | **Reporter**    |
+
+- **Propriétaire du projet** : **Owner** (toujours le niveau le plus élevé, indépendamment des rôles).
+- **Cumul des rôles** : en cas de rôles multiples, le **niveau le plus élevé** l'emporte.
+- **Rôle sans groupe OIDC reconnu** : le membre reçoit **Guest** (accès minimal au groupe).
+- **Rôles plateforme** : les membres d'`/console/admin` reçoivent le flag GitLab **admin** (administration de l'instance) ; les membres des groupes d'audit (`/console/readonly`, `/console/security`) reçoivent le flag **auditor** (lecture sur toute l'instance).
+### Adaptation par configuration du plugin GitLab
+
+| Clé                                  | Rôle                                    | Valeur par défaut                 |
+| ------------------------------------ | --------------------------------------- | --------------------------------- |
+| `projectMaintainerGroupPathSuffix`   | Suffixes OIDC donnant l'accès **Maintainer** | `/console/admin,/console/devops`  |
+| `projectDeveloperGroupPathSuffix`    | Suffixe OIDC donnant l'accès **Developer**   | `/console/developer`              |
+| `projectReporterGroupPathSuffix`     | Suffixes OIDC donnant l'accès **Reporter**   | `/console/readonly,/console/security` |
+| `adminGroupPath`                     | Groupe OIDC donnant le flag **admin** GitLab | `/console/admin`               |
+| `auditorGroupPath`                   | Groupes OIDC donnant le flag **auditor** GitLab | `/console/readonly,/console/security` |
+
+## 3. Points d'attention
+
+- **Provisionnement autoritaire.** La Console aligne systématiquement le niveau d'accès de chaque membre tracé : les modifications manuelles dans GitLab sont écrasées à la synchronisation. Les membres non tracés par la Console sont **supprimés** uniquement lorsque la purge est activée (config plugin `purge` = `enabled`) ; sinon ils sont seulement signalés dans les journaux.
+- Les dépôts `infra-apps` et `mirror` sont des dépôts techniques Console, jamais des cibles de mirroring.
+
+## 4. Qui gère quoi ?
+
+| Élément                            | Géré par                  |
+| ---------------------------------- | ------------------------- |
+| Identité OIDC / groupes Keycloak   | **Keycloak**              |
+| Groupes GitLab, membres & niveaux  | **Console** (automatique) |
+| Application des droits             | **GitLab**                |
diff --git a/docs/guide/roles.md b/docs/guide/roles.md
@@ -83,37 +83,13 @@ Pour les identifier, vérifier que les champs de paramétrage sont non modifiabl
 
 ![Paramétrage d’un rôle lecture seule](/img/iam/project-role-readonly.png)
 
-## Vérification dans les services intégrés (exemple GitLab)
+## Vérification dans les services intégrés
 
-La Console est la source de vérité des rôles projet. Selon les intégrations actives et le niveau de synchronisation, l’affectation à un rôle peut se traduire par des droits visibles dans des services externes.
+La Console est la source de vérité des rôles projet. Selon les intégrations actives et le niveau de synchronisation, l'affectation à un rôle peut se traduire par des droits visibles dans des services externes.
 
-Si aucune intégration externe n’est active, la vérification se fait uniquement dans la Console (onglets `Équipe` et `Rôles`).
+Si aucune intégration externe n'est active, la vérification se fait uniquement dans la Console (onglets `Équipe` et `Rôles`).
 
-À ce jour, GitLab est le service intégré pour ce contrôle.
-
-Correspondance des rôles projet vers GitLab (par défaut) :
-
-| Rôle projet (Console) | Droits GitLab sur le groupe du projet |
-| --- | --- |
-| Administrateur (`/console/admin`) | Maintainer |
-| DevOps (`/console/devops`) | Developer |
-| Développeur (`/console/developer`) | Developer |
-| Lecture seule (`/console/readonly`) | Reporter |
-| Propriétaire du projet (Console) | Owner |
-
-Cette correspondance peut être adaptée par les administrateurs via la configuration du plugin GitLab.
-
-:::warning
-**Phase de rétrocompatibilité (9.16.x)** — **GitLab** attribue toujours le rôle `Développeur` par défaut lors de l'ajout d'un membre. Le rôle `Lecture seule` de la Console (`/console/readonly`, normalement dédié aux personnes chargés de faire des rapports ou des audits) n'a donc aucun effet sur **Gitlab**. Ce comportement est conservé temporairement pour compatibilité ; Il évoluera vers le rôle **Gitlab** `Invité` dans une prochaine version.
-:::
-
-:::danger
-**Changement cassant** — Les rôles sont désormais provisionnés de manière autoritaire dans les services intégrés (GitLab). La Console prend le contrôle total de l'appartenance : tout membre non tracé par la Console sera **supprimé**, et seuls les membres assignés via les rôles Console seront **ajoutés**. Ce comportement empêche toute dérive entre la Console et les services externes. Les modifications manuelles de membership dans GitLab seront écrasées lors de la synchronisation.
-:::
-
-Exemple (GitLab) :
-
-![GitLab - membres du groupe](/img/iam/gitlab-group-members.png)
+À ce jour, GitLab est le service intégré pour ce contrôle : la correspondance groupes Keycloak → niveaux d'accès est détaillée dans la fiche [Groupes Keycloak et GitLab](/guide/rbac/gitlab).
 
 ## Exemple de rôle