Apidog peut se connecter aux tenants de résidence de données GitHub Enterprise Cloud hébergés sur des domaines dédiés *.ghe.com. Une fois qu'un administrateur d'organisation a configuré le tenant et l'application OAuth, les utilisateurs de projet autorisés peuvent connecter des dépôts et utiliser les flux de travail d'importation, de sauvegarde et de synchronisation OpenAPI pris en charge.
Cette intégration est destinée aux tenants SaaS de résidence de données GitHub Enterprise Cloud. Elle ne prend pas en charge GitHub Enterprise Server ou les domaines GitHub personnalisés arbitraires.
Avant de commencer
Vous avez besoin :
- d'une organisation Apidog Enterprise ayant accès à l'intégration
- de la permission d'administrateur d'organisation dans Apidog
- d'un tenant de résidence de données GitHub Enterprise Cloud sur un domaine racine
*.ghe.com, tel quehttps://company.ghe.com - de la permission de créer une application OAuth sur ce tenant
- d'un accès aux organisations, dépôts et branches GitHub que vous prévoyez de connecter
Les utilisateurs qui connectent des dépôts doivent également avoir la permission de connexion Git au niveau du projet pertinente dans Apidog.
Étape 1 : Créer une application OAuth sur le tenant GHE.com
- Connectez-vous au tenant GHE.com de votre organisation.
- Ouvrez les paramètres des applications OAuth.
- Créez une nouvelle application OAuth.
- Saisissez un nom d'application identifiable.
- Définissez l'URL de la page d'accueil sur :
https://apidog.com - Définissez l'URL de rappel d'autorisation sur :
https://api.apidog.com/passport/github/callback - Enregistrez l'application OAuth.
- Copiez l'ID client.
- Générez et copiez en toute sécurité le Secret client.
L'URL de rappel doit correspondre exactement à l'URL Apidog documentée.
Stockez le Secret client dans votre système de gestion des secrets approuvé. Ne le placez pas dans une capture d'écran, un ticket ou un document partagé.
Étape 2 : Configurer le tenant GHE.com dans Apidog
Seul un administrateur d'organisation peut configurer ou désactiver cette intégration.
- Ouvrez l'organisation Apidog.
- Accédez à Paramètres de l'organisation.
- Ouvrez Intégration GitHub.
- Recherchez Résidence des données GitHub Enterprise Cloud et sélectionnez Configurer.
- Saisissez l'URL d'hôte GHE.com, par exemple
https://company.ghe.com. - Sélectionnez Application OAuth comme méthode d'authentification.
- Saisissez l'ID client de l'application OAuth.
- Saisissez le Secret client de l'application OAuth.
- Enregistrez la configuration.
Configurez l'hôte du tenant et les identifiants de l'application OAuth au niveau de l'organisation.
Après l'enregistrement, Apidog affiche l'URL d'hôte configurée. Le Secret client n'est pas affiché ou pré-rempli à nouveau.
Lors de la modification ultérieure de la configuration, laisser le champ Secret client vide conserve le secret existant. Saisissez une nouvelle valeur uniquement lors de sa rotation.
Étape 3 : Connecter un dépôt à partir d'un projet Apidog
Une fois la configuration au niveau de l'organisation terminée :
- ouvrez le projet Apidog requis ;
- démarrez un flux de travail de connexion Git ou d'importation Git ;
- sélectionnez GitHub Enterprise Cloud ;
- continuez vers la page d'autorisation sur le tenant GHE.com configuré ;
- connectez-vous et autorisez l'application OAuth ;
- sélectionnez l'organisation GitHub ;
- sélectionnez le dépôt et la branche ;
- terminez la connexion.
L'autorisation est effectuée sur le tenant GHE.com configuré, et non sur github.com standard.
Si l'organisation ou le dépôt attendu est manquant, vérifiez l'accès du compte GitHub et l'autorisation de l'application OAuth avant de modifier les paramètres de l'organisation Apidog.
Étape 4 : Importer un fichier OpenAPI
Pour importer un fichier OpenAPI ou Swagger depuis le dépôt connecté :
- démarrez un flux de travail d'importation dans le projet Apidog ;
- choisissez OpenAPI/Swagger ;
- sélectionnez Dépôt Git ;
- choisissez l'organisation GitHub, le dépôt, la branche et le fichier ;
- sélectionnez Continuer ;
- choisissez un module cible existant ou créez-en un nouveau ;
- terminez l'importation ;
- examinez les points de terminaison et les schémas importés avant d'accepter le résultat.
Sélectionnez le dépôt, la branche et le fichier de spécification requis par le projet.
Utilisez un projet hors production pour la première importation, surtout lorsque le module cible contient déjà des définitions d'API.
Étape 5 : Choisir le flux de travail de synchronisation continue
La connexion au dépôt peut prendre en charge différents flux de travail. Choisissez une source de vérité et documentez-la pour l'équipe.
| Flux de travail | Utiliser quand | Comportement important |
|---|---|---|
| Importation manuelle | Les modifications sont importées dans Apidog uniquement sur demande | Examinez chaque importation et module cible |
| Importation planifiée | Le fichier Git reste la source et Apidog doit le rafraîchir à un certain intervalle | S'exécute via le client local ou un Runner auto-hébergé selon le mode d'exécution configuré |
| Sauvegarde vers Git | Le contenu d'Apidog doit être écrit dans un fichier de dépôt | Configurez le dépôt, la branche et le chemin du fichier cible ; les sauvegardes automatiques s'exécutent pendant une période creuse nocturne planifiée de manière aléatoire |
| Mode Spec-first | Le fichier de spécification est la source de vérité et l'équipe édite via un flux de travail orienté Git | Ce mode est actuellement en version bêta ; l'installation de webhook nécessite généralement la permission d'administrateur de dépôt |
Ne configurez pas deux flux de travail automatisés opposés pour le même fichier sans une règle de résolution de conflit claire.
Pour la sauvegarde :
- créez ou sélectionnez la connexion Git dans les paramètres du projet ;
- ouvrez Aperçu > Spécification API du module ;
- ajoutez ou sélectionnez la spécification OpenAPI ;
- activez Sauvegarde vers le dépôt Git ;
- choisissez la connexion au dépôt, la branche et le chemin du fichier cible ;
- enregistrez la configuration.
Pour une source de vérité basée sur le dépôt, utilisez l'Importation planifiée ou examinez le Mode Spec-first.
Étape 6 : Vérifier l'intégration
Exécutez un petit test de bout en bout :
- confirmez que l'autorisation ouvre le tenant GHE.com configuré
- confirmez que seules les organisations et les dépôts attendus sont disponibles
- importez un fichier OpenAPI connu et comparez le résultat avec la source
- testez la direction de sauvegarde ou de synchronisation sélectionnée dans une branche jetable
- confirmez que la protection des branches et les permissions du dépôt se comportent comme prévu
- examinez les journaux de synchronisation ou les erreurs
- faites pivoter le Secret client de l'application OAuth et confirmez que le processus de mise à jour documenté fonctionne
Si la synchronisation par webhook est utilisée, vérifiez que l'installateur dispose des permissions d'administrateur de dépôt et que l'événement de push attendu déclenche la synchronisation.
Mettre à jour ou effacer les paramètres de l'organisation
Les administrateurs d'organisation peuvent modifier l'URL de l'hôte ou l'ID client et peuvent faire pivoter le Secret client en saisissant une nouvelle valeur.
Pour supprimer la configuration au niveau de l'organisation, ouvrez Paramètres de l'organisation > Intégration GitHub, recherchez l'intégration de résidence de données et sélectionnez Effacer les paramètres.
Une fois les paramètres effacés, les utilisateurs ne peuvent plus créer de nouvelles connexions GitHub Enterprise Cloud tant que l'intégration n'est pas reconfigurée. Les connexions existantes peuvent nécessiter une reconfiguration ou une réautorisation en fonction de l'état du jeton et des paramètres de l'organisation.
Dépannage
| Problème | Que vérifier |
|---|---|
| L'option d'intégration est indisponible | Confirmez que l'organisation a accès à la fonctionnalité Enterprise et que vous êtes un administrateur d'organisation. |
| OAuth renvoie une erreur de rappel | Confirmez que le rappel de l'application OAuth est exactement https://api.apidog.com/passport/github/callback. |
| L'autorisation ouvre github.com | Confirmez que l'hôte au niveau de l'organisation est le tenant racine *.ghe.com prévu. |
| Un dépôt est manquant | Vérifiez l'accès à l'organisation et au dépôt de l'utilisateur GitHub autorisé et les éventuelles restrictions OAuth. |
| Un utilisateur de projet ne peut pas créer de connexion | Confirmez que l'utilisateur dispose de la permission de connexion Git au niveau du projet requise. |
| L'importation ou la synchronisation échoue | Vérifiez la branche sélectionnée, le chemin du fichier, le format du fichier, les permissions du dépôt et les journaux de synchronisation. |
Limites de sécurité et de résidence des données
- Seuls les administrateurs d'organisation peuvent configurer ou désactiver l'intégration GHE.com.
- Le Secret client n'est pas affiché après la configuration.
- Les permissions de projet contrôlent toujours qui peut créer ou mettre à jour les connexions Git.
- L'autorisation OAuth se fait via le tenant GHE.com configuré.
- Les permissions OAuth demandées peuvent inclure l'accès nécessaire pour lire les organisations, les dépôts, les branches, importer des fichiers, écrire des sauvegardes et gérer les webhooks de dépôt lorsque requis par un flux de travail de synchronisation.
La connexion d'un tenant de résidence de données ne prouve pas en soi que chaque catégorie de données liées à GitHub ou Apidog reste dans une seule région. GitHub documente les données couvertes par son offre de résidence et les exceptions pertinentes. Apidog est un service connecté séparé avec son propre modèle de stockage et de déploiement. Examinez la documentation actuelle des deux fournisseurs dans le cadre d'une évaluation de la résidence des données ou de la conformité.
Tutoriels de gouvernance d'API connexes :
Ces tutoriels couvrent des contrôles complémentaires pour la gouvernance d'un espace de travail API d'entreprise :
- Cadre de gouvernance d'API — relier la propriété, les contrôles, les preuves et les décisions du cycle de vie.
- Mappage de groupes SAML avec Microsoft Entra ID — attribuer l'accès d'équipe à partir de groupes de fournisseurs d'identité.
- Scanner de secrets — examiner les identifiants potentiellement exposés dans les actifs Apidog pris en charge.
- Journaux d'audit — enquêter et exporter l'activité administrative de l'organisation.
- Provisionnement SCIM — gérer les utilisateurs de l'organisation tout au long du cycle de vie de l'identité.
- Politiques d'entreprise — configurer les contrôles d'identifiants, d'adhésion, de session SSO et d'invitation.
- Équipes API en libre-service gouvernées — permettre aux équipes créées par les membres tout en conservant la supervision de la propriété.
- Intégration GitHub Enterprise Cloud — connecter les dépôts GHE.com pris en charge pour les flux de travail OpenAPI.
Documentation officielle connexe :