GitLab

Connectez votre dépôt GitLab à Mintlify pour des déploiements automatisés, des prévisualisations de merge requests et une synchronisation continue.

Mintlify utilise des jetons d’accès et des webhooks pour authentifier et synchroniser les changements entre GitLab et Mintlify.

• Mintlify utilise des jetons d’accès pour récupérer des informations depuis GitLab.
• GitLab utilise des webhooks pour avertir Mintlify lorsque vous effectuez des changements, ce qui permet des déploiements de prévisualisation pour les merge requests.

​

Configurer la connexion

Lorsque vous ouvrez Git Settings pour la première fois, un assistant de configuration vous guide pour connecter votre référentiel GitLab.

1. Sélectionner GitLab comme fournisseur

   Sur la page Git Settings, sélectionnez Connect to GitLab et cliquez sur Continue.

2. Télécharger votre contenu

   Si vous disposez déjà d’un référentiel GitLab contenant votre documentation, vous pouvez ignorer le téléchargement et cliquer directement sur Continue setup.

   Si votre documentation est hébergée par Mintlify, téléchargez-la sous forme de fichier zip.

   • Créez un nouveau référentiel dans GitLab.
   • Extrayez le contenu du zip.
   • Poussez le contenu vers votre référentiel.

   Cliquez sur Continue setup pour continuer.

3. Trouver votre ID de projet

   Dans votre projet GitLab, accédez à Settings > General et repérez votre Project ID.

   
4. Générer un jeton d'accès

   Accédez à Settings > Access Tokens et sélectionnez Add new token.

   Configurez le jeton avec les paramètres suivants :

   • Name : Mintlify
   • Role : Maintainer (requis pour les référentiels privés)
   • Scopes : api et read_api

   Cliquez sur Create project access token et copiez le jeton.

   Si les Project Access Tokens ne sont pas disponibles, vous pouvez utiliser un Personal Access Token. Notez que les Personal Access Tokens expirent et doivent être renouvelés.

   
5. Connecter votre référentiel

   De retour dans l’assistant de configuration, remplissez les champs suivants :

   • GitLab instance URL : Laissez vide pour gitlab.com, ou saisissez l’URL de votre instance auto-hébergée (par exemple, https://gitlab.your-domain.com). Votre instance doit être accessible publiquement pour que Mintlify puisse s’y connecter.
   • Project ID : L’ID de projet depuis les paramètres de votre projet GitLab.
   • GitLab deployment token : Le jeton d’accès que vous avez généré.
   • Branch : Sélectionnez la branche à partir de laquelle déployer votre documentation.

   Cliquez sur Connect.

   

​

Mettre à jour une connexion existante

Pour modifier les paramètres de votre connexion GitLab après la configuration initiale, accédez à Git Settings et mettez à jour votre ID de projet, jeton d’accès, branche ou URL d’instance directement.

​

Revalider les paramètres Git

Si votre déploiement affiche un comportement inattendu, comme des options de branche manquantes ou une configuration obsolète, vous pouvez forcer Mintlify à actualiser votre source Git.

1. Accéder aux paramètres Git

   Accédez aux Git Settings dans votre Tableau de bord.

2. Revalider vos paramètres

   Cliquez sur le badge vert Active dans le coin du cadre des paramètres GitLab pour revalider votre source Git. Un toast de succès confirme la fin de la revalidation, et un toast d’erreur apparaît si votre configuration nécessite une vérification.

​

Créer le webhook

Les webhooks notifient Mintlify lorsque vous poussez des modifications afin que les déploiements se déclenchent automatiquement.

1. Ajouter un nouveau webhook

   1. Dans GitLab, accédez à Settings > Webhooks.
   2. Cliquez sur Add new webhook.

   
2. Configurer l'URL et le webhook

   Nommez le webhook Mintlify.

   Dans le champ URL, saisissez le point de terminaison https://leaves.mintlify.com/gitlab-webhook.

3. Récupérer le webtoken

   Dans votre Tableau de bord Mintlify, cliquez sur Show Webtoken. Copiez le webtoken.

   
4. Coller le webtoken

   Dans GitLab, collez le webtoken depuis votre Tableau de bord Mintlify dans le champ Secret token.

5. Sélectionner les événements

   Sélectionnez les événements suivants pour déclencher le webhook :

   • Push events (All branches)
   • Merge requests events
6. Vérifier le webhook

   Vous devriez voir les paramètres suivants après avoir configuré le webhook :

   • Name : Mintlify
   • URL : https://leaves.mintlify.com/gitlab-webhook
   • Secret token : le webtoken depuis votre Tableau de bord Mintlify
   • Events : Push events (All branches) et Merge requests events

   Ajoutez le webhook.

   
7. Tester le webhook

   Après avoir créé le webhook, cliquez sur le menu déroulant Test. Cliquez sur Push events pour envoyer un payload d’exemple. Si le test renvoie Hook executed successfully: HTTP 200, vous avez correctement configuré le webhook.

   

​

GitLab auto-hébergé via OAuth

Si vous exécutez GitLab sur votre propre infrastructure, vous pouvez connecter votre instance auto-hébergée à Mintlify via OAuth. Cette connexion est utilisée par les workflows et l’agent pour lire les dépôts, écouter les événements de push et de merge request, et ouvrir des merge requests.

GitLab auto-hébergé via OAuth est actuellement disponible sur les forfaits Enterprise. Contactez votre représentant Mintlify si vous ne voyez pas l’option dans votre Tableau de bord.

Connecter une instance auto-hébergée se fait en deux étapes :

1. Enregistrez une application OAuth sur votre instance GitLab.
2. Enregistrez les identifiants de l’application dans votre Tableau de bord Mintlify, puis autorisez la connexion.

​

Enregistrer une application OAuth sur votre instance GitLab

Vous pouvez enregistrer l’application OAuth comme une application à l’échelle de l’instance (admin uniquement) ou comme une application appartenant à un groupe. Une application appartenant à un groupe est généralement suffisante et ne nécessite pas d’accès admin.

1. Ouvrir les paramètres d'application

   Connectez-vous à votre instance GitLab en tant qu’admin ou propriétaire de groupe.

   • À l’échelle de l’instance : allez dans Admin Area > Applications et cliquez sur Add new application.
   • Appartenant à un groupe : ouvrez votre groupe, puis allez dans Settings > Applications et cliquez sur Add new application.
2. Configurer l'application

   Utilisez ces valeurs :

   • Name : Mintlify
   • Redirect URI : https://leaves.mintlify.com/gitlab-oauth/callback
   • Confidential : activé
   • Scopes : api et read_api

   Enregistrez l’application.

3. Copier les identifiants

   GitLab affiche l’Application ID et le Secret. Copiez les deux valeurs maintenant — le secret n’est affiché qu’une seule fois.

​

Enregistrer les identifiants dans votre Tableau de bord Mintlify

1. Ouvrir Git Settings

   Allez dans Git Settings et trouvez la carte Self-hosted GitLab dans la section GitLab OAuth.

2. Saisir les détails de votre instance

   Cliquez sur Connect Self-Hosted GitLab et remplissez :

   • GitLab instance URL : l’URL de base de votre instance (par exemple, https://gitlab.your-company.com). Doit commencer par https:// ou http://.
   • OAuth application client ID : l’Application ID de l’étape précédente.
   • OAuth application client secret : le Secret de l’étape précédente. Chiffré au repos et jamais renvoyé par l’API après l’enregistrement.

   Cliquez sur Save instance.

3. Autoriser la connexion

   Cliquez sur Authorize self-hosted GitLab. Vous serez redirigé vers votre instance GitLab pour approuver les scopes OAuth, puis renvoyé vers le Tableau de bord.

   Après l’autorisation, développez la nouvelle connexion pour parcourir les groupes et activer des projets individuels.

​

Gérer la connexion

• Ajouter plusieurs utilisateurs : chaque membre de votre organisation peut autoriser son propre compte GitLab sur la même instance auto-hébergée. Cliquez sur Add another GitLab connection pour ajouter d’autres utilisateurs.
• Faire tourner les identifiants : pour faire tourner le client secret, supprimez l’instance enregistrée et ajoutez-la à nouveau avec la nouvelle valeur. Vous devez d’abord révoquer toutes les connexions OAuth actives.
• Supprimer l’instance : cliquez sur Remove instance sur la carte Self-hosted GitLab. Les webhooks existants pour les projets connectés sont supprimés.

​

Prérequis

• L’instance GitLab doit être joignable depuis leaves.mintlify.com. Mintlify ne peut pas se connecter à des instances derrière un VPN ou une liste d’IP autorisées qui bloque notre trafic sortant.
• Vous devez avoir au moins le rôle Maintainer sur chaque projet GitLab que vous souhaitez connecter, afin que Mintlify puisse installer des webhooks.
• Une seule instance auto-hébergée peut être configurée par organisation Mintlify.