Passer au contenu principal
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

L’intégration nécessite du trafic dans les deux directions entre votre instance GHES et Mintlify. Configurez votre pare-feu pour autoriser les deux connexions suivantes.

​
Sortant : de votre instance GHES vers Mintlify

Votre instance GHES délivre les événements de webhook à Mintlify via HTTPS (port 443) à leaves.mintlify.com.
  • Autorisez le trafic sortant HTTPS (port 443) vers leaves.mintlify.com. Autorisez ce trafic par nom d’hôte. Mintlify ne publie pas de liste d’adresses IP statiques pour ce point de terminaison, et ses adresses IP sous-jacentes peuvent changer.
  • Assurez-vous que votre instance GHES peut résoudre leaves.mintlify.com via DNS. Si vos serveurs utilisent un résolveur DNS interne, vérifiez qu’il résout les noms d’hôtes publics.

​
Entrant : de Mintlify vers votre instance GHES

Mintlify se connecte à votre instance GHES via HTTPS (port 443) pour appeler l’API GitHub, remonter les statuts des check runs et des déploiements, et lire le contenu du dépôt. Ces connexions proviennent de l’adresse IP statique d’egress de Mintlify : 54.242.90.151. Si un pare-feu ou une liste d’adresses IP autorisées restreint l’accès à votre instance GHES, autorisez le trafic entrant HTTPS (port 443) depuis 54.242.90.151.
Les exécutions de l’agent clonent et poussent depuis une infrastructure de sandbox distincte qui utilise par défaut des adresses IP dynamiques. Si votre instance GHES applique une liste d’adresses IP autorisées, voir Résoudre les exécutions d’agent bloquées par une liste d’adresses IP autorisées.

​
É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. L’application n’a besoin d’aucune autorisation au niveau de l’organisation, du compte ou de l’entreprise :
  • 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.GitHub vous redirige 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

Sélectionner 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)
  • Installation owner : le nom de l’organisation GitHub propriétaire de l’installation de l’app
  • Clé privée : l’intégralité du contenu du fichier .pem (partagez-la via un transfert de fichier sécurisé)
  • Secret du webhook : (à partir de l’étape 5)

​
Identifiants facultatifs pour le dépannage

  • Repository names: Dépôts spécifiques où vous avez installé l’application
  • 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 projet Mintlify existant.
  • Intégrer votre environnement GHES à un nouveau projet Mintlify que nous mettons en place pour vous.
Une fois que vous avez intégré votre environnement GHES à un projet 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

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
  • 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 que vous avez configuré.
  • Consultez les journaux de livraison des webhooks dans l’onglet « Advanced » des paramètres de votre GitHub App.
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.
  • Assurez-vous que notre serveur reçoit et accuse réception des webhooks avec un code de réponse 200.
  • Vous avez accordé les autorisations requises lors de l’installation.
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.
  • 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 que vous pourriez devoir suivre.
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.
Non, votre GHES doit pouvoir communiquer avec notre serveur hébergé dans le cloud.
Veuillez contacter votre représentant Customer Success avec qui vous avez échangé chez Mintlify, ou notre équipe support à l’adresse support@mintlify.com 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).

Sujets connexes

IP statique de Mintlify pour allowlists GitAuto-hébergementGitHub