GitHub Enterprise Server

Installez et configurez l’application GitHub Mintlify sur votre instance GitHub Enterprise Server pour des déploiements automatiques de documentation et la synchronisation.

Ce guide vous explique comment configurer l’App GitHub Mintlify sur votre installation GitHub Enterprise Server (GHES). Pour connecter une instance GHES à Mintlify, vous devez créer une version locale de notre application au sein de votre environnement auto‑hébergé, qui communique avec notre serveur distant.

Si vous utilisez une instance GitHub hébergée sur le cloud, consultez la page GitHub pour les instructions de configuration.

​

Prérequis

• Droits d’administrateur sur votre organisation GitHub Enterprise Server où vous souhaitez installer l’application
• Accès aux dépôts de votre organisation où vous souhaitez installer l’application
• Connectivité réseau pour communiquer avec nos services externes (voir la section Exigences réseau ci-dessous)

​

Prérequis réseau

​

Connectivité sortante

Votre GitHub Enterprise Server doit pouvoir accéder à :

• les points de terminaison de l’API Mintlify (https://leaves.mintlify.com)
• les récepteurs de webhook (port 443)

​

Configuration du pare-feu

Les connexions sortantes suivantes doivent être autorisées :

• Connexions provenant de l’adresse IP statique de Mintlify : 54.242.90.151
• HTTPS (port 443) vers les domaines de service de Mintlify
• Résolution DNS pour les domaines de service de Mintlify

​

Étape 1 : Enregistrer l’application GitHub

Consultez la page Registering a GitHub App dans la documentation GitHub pour des instructions détaillées.

1. Accéder aux paramètres de votre organisation

   1. Dans le coin supérieur droit de n’importe quelle page sur GitHub, cliquez sur votre photo de profil.
   2. Cliquez sur Your organizations.
   3. Cliquez sur Settings à côté de l’organisation pour laquelle vous souhaitez créer l’application.
2. Créer une nouvelle application GitHub

   1. Dans la barre latérale gauche, cliquez sur Developer settings.
   2. Cliquez sur GitHub Apps.
   3. Cliquez sur New GitHub App.
3. Configurer les informations de base de l'application

   Définissez les éléments suivants :

   • GitHub App name : Mintlify
   • Description : Intégration avec les services Mintlify
   • Homepage URL : https://mintlify.com
   • User authorization callback URL : https://your-github-server.com/ (remplacez par votre domaine GHES réel)

​

Étape 2 : Configurer les autorisations de l’application

1. Définir les autorisations du dépôt

   Définissez les autorisations suivantes pour l’application. Aucune autorisation au niveau de l’organisation, du compte ou de l’entreprise n’est requise :

   • Checks : lecture et écriture
   • Contents : lecture et écriture
   • Deployments : lecture et écriture
   • Metadata : lecture seule
   • Pull Requests : lecture et écriture
2. S'abonner aux événements

   Sélectionnez les événements de webhook suivants :

   • Installation
   • Installation Target
   • Create
   • Delete
   • Public
   • Pull Request
   • Push
   • Repository

​

Étape 3 : Générer et sécuriser les identifiants

1. Créer l'application

   Cliquez sur Create GitHub App.

   Vous serez redirigé vers la page de paramètres de l’application.

2. Générer la clé privée

   1. Faites défiler la page jusqu’à la section Private keys.
   2. Cliquez sur Generate a private key.
   3. Téléchargez le fichier .pem et conservez-le en lieu sûr.
3. Noter les identifiants de l'application

   Notez les informations suivantes :

   • App ID (visible en haut de la page de paramètres)
   • Client ID (dans la section “About”)
   • Client Secret (générez-le et conservez-le en lieu sûr)

​

Étape 4 : Installer l’application

1. Accéder à l'installation de l'application

   1. Sur la page des paramètres de l’application, cliquez sur Install App dans la barre latérale gauche.
   2. Sélectionnez votre organisation dans la liste.
2. Choisir la portée de l'installation

   Sélectionnez l’une des options suivantes :

   • All repositories (pour un accès à l’ensemble de l’organisation)
   • Only select repositories (choisir des dépôts spécifiques)

   Nous vous recommandons de sélectionner Only select repositories et de limiter l’application uniquement aux dépôts où votre documentation est hébergée.

3. Terminer l'installation

   1. Cliquez sur Install.
   2. Notez l’ID d’installation à partir de l’URL. Par exemple, dans https://your-github-server.com/settings/installations/12345, la chaîne 12345 correspond à l’ID d’installation.

​

Étape 5 : Configurer l’URL du webhook

1. Revenir aux paramètres de l’app

   1. Revenez à la page de paramètres de votre app.
   2. Faites défiler jusqu’à la section Webhook.
2. Définir l’URL du webhook

   Configurez ce qui suit :

   • Webhook URL : https://leaves.mintlify.com/github-enterprise/:subdomain (remplacez :subdomain par l’URL que nous vous fournirons)
   • Webhook secret : Générez une chaîne de caractères aléatoire d’au moins 32 caractères et conservez-la en lieu sûr. Mintlify peut également la générer et vous la fournir.

​

Partagez vos identifiants avec nous

Veuillez partager les informations suivantes avec notre équipe en utilisant la méthode sécurisée de transmission d’informations de votre choix.

​

Identifiants requis

• URL de base de votre GitHub Enterprise Server : https://your-github-server.com
• ID de l’application : (à partir de l’étape 3)
• ID client de l’application : (à partir de l’étape 3)
• Secret client de l’application : (à partir de l’étape 3)
• ID d’installation : (à partir de l’étape 4)
• Clé privée : l’intégralité du contenu du fichier .pem (à partager via un transfert de fichier sécurisé)
• Secret du webhook : (à partir de l’étape 5)

​

Identifiants facultatifs pour le dépannage

• Organization name: Le nom de votre organisation GitHub
• Repository names: Dépôts spécifiques où l’application est installée
• GitHub Enterprise Server version: Indiquée dans le tableau de bord d’administration de votre site

​

Connexion à Mintlify

Nous chiffrons et stockons les identifiants que vous nous fournissez dans un emplacement sécurisé. Ensuite, nous collaborons avec vous pour :

• Intégrer votre environnement GHES à un déploiement Mintlify existant.
• Intégrer votre environnement GHES à un nouveau déploiement Mintlify que nous mettons en place pour vous.

Une fois que votre environnement GHES est intégré à un déploiement Mintlify, vous êtes prêt à activer les webhooks pour votre GitHub App.

L’URL du webhook peut changer en fonction de notre configuration. Nous testons l’intégration et vous communiquons la nouvelle URL.

​

Tester l’intégration

1. Vérifier la bonne réception des webhooks

   1. Allez dans les paramètres de votre GitHub App.
   2. Cliquez sur l’onglet Advanced.
   3. Consultez la section “Recent deliveries” pour confirmer la réussite des envois de webhooks.
   4. Recherchez les réponses HTTP 200.
2. Tester l’accès au dépôt

   1. Créez une issue ou une pull request de test dans un dépôt où l’application est installée.
   2. Vérifiez que Mintlify réagit comme attendu.

​

FAQ et dépannage

L'installation de l'application échoue avec des erreurs d'autorisations.

Assurez-vous de disposer de :

• Privilèges d’administrateur du site pour la création d’applications
• Droits de propriétaire ou d’administrateur de l’organisation pour l’installation de l’application
• Autorisations de dépôt appropriées si vous installez l’application sur des dépôts spécifiques

Les webhooks ne sont pas reçus

• Vérifiez que l’URL du webhook est correcte et accessible.
• Assurez-vous que votre pare-feu autorise les connexions HTTPS sortantes.
• Vérifiez que le secret du webhook correspond à celui configuré.
• Consultez les journaux de livraison des webhooks dans l’onglet « Advanced » des paramètres de votre GitHub App.

Je reçois des erreurs de certificat SSL/TLS

Votre GHES peut utiliser des certificats auto-signés. Nos services ne peuvent pas vérifier le certificat de votre serveur.

Solution : Assurez-vous que votre GHES dispose d’un certificat SSL valide.

L'application s'installe, mais ne réagit pas aux événements.

• Assurez-vous que les webhooks sont bien livrés et accusés de réception par notre serveur avec un code de réponse 200.
• Vérifiez que les autorisations requises ont été accordées lors de l’installation.

Puis-je limiter les dépôts auxquels l'application accède ?

Oui, lors de l’installation, vous pouvez sélectionner « Only select repositories » et choisir des dépôts spécifiques. Vous pouvez modifier ce paramètre plus tard dans les paramètres des applications installées de votre organisation. C’est la méthode d’installation recommandée.

Comment mettre à jour les autorisations de l'application ultérieurement ?

• Accédez aux paramètres de l’application en tant qu’administrateur du site.
• Modifiez les autorisations selon vos besoins.
• L’application doit être à nouveau approuvée par les propriétaires de l’organisation.
• Informez-nous de toute modification d’autorisations afin que nous puissions vous conseiller sur les étapes supplémentaires éventuellement requises.

Notre GHES se trouve derrière un pare-feu d'entreprise, un proxy nginx ou une configuration similaire.

Vous devez :

• Ajoutez nos domaines de service à la liste d’autorisation de votre pare-feu.
• Assurer la connectivité HTTPS sortante (port 443).
• Si l’accès direct à Internet n’est pas autorisé, configurer un proxy.

Est-ce que cela fonctionne avec un GHES dans des environnements isolés (air-gapped) ?

Non, votre GHES doit pouvoir communiquer avec notre serveur hébergé dans le cloud.

Qui dois-je contacter si j'ai besoin d'aide ?

Veuillez contacter votre représentant Customer Success avec qui vous avez échangé chez Mintlify, ou notre équipe support à l’adresse [e-mail] avec :

• Votre version de GitHub Enterprise Server.
• Les messages d’erreur spécifiques.
• Des captures d’écran des problèmes rencontrés.
• Les détails de la configuration réseau/pare-feu (le cas échéant).