Apidog kann sich mit GitHub Enterprise Cloud Data-Residency-Mandanten verbinden, die auf dedizierten *.ghe.com-Domains gehostet werden. Nachdem ein Organisationsadministrator den Mandanten und die OAuth-App konfiguriert hat, können autorisierte Projektbenutzer Repositories verbinden und unterstützte OpenAPI-Import-, Backup- und Synchronisierungsworkflows nutzen.
Diese Integration ist für GitHub Enterprise Cloud Data-Residency SaaS-Mandanten vorgesehen. Sie unterstützt weder GitHub Enterprise Server noch beliebige benutzerdefinierte GitHub-Domains.
Bevor Sie beginnen
Sie benötigen:
- eine Apidog Enterprise-Organisation mit Zugriff auf die Integration
- Organisationsadministrator-Berechtigung in Apidog
- einen GitHub Enterprise Cloud Data-Residency-Mandanten auf einer Stamm-
*.ghe.com-Domain, z. B.https://company.ghe.com - Berechtigung zur Erstellung einer OAuth-App auf diesem Mandanten
- Zugriff auf die GitHub-Organisationen, Repositories und Branches, die Sie verbinden möchten
Benutzer, die Repositories verbinden, müssen auch die entsprechende Projekt-Level-Git-Verbindungsberechtigung in Apidog besitzen.
Schritt 1: Eine OAuth-App auf dem GHE.com-Mandanten erstellen
- Melden Sie sich beim GHE.com-Mandanten Ihrer Organisation an.
- Öffnen Sie die Einstellungen für OAuth-Apps.
- Erstellen Sie eine neue OAuth-App.
- Geben Sie einen eindeutigen Anwendungsnamen ein.
- Setzen Sie die Homepage-URL auf:
https://apidog.com - Setzen Sie die Autorisierungs-Callback-URL auf:
https://api.apidog.com/passport/github/callback - Registrieren Sie die OAuth-App.
- Kopieren Sie die **Client ID**.
- Generieren und kopieren Sie das **Client Secret** sicher.
Die Callback-URL muss exakt mit der dokumentierten Apidog-URL übereinstimmen.
Speichern Sie das Client Secret in Ihrem genehmigten Geheimnisverwaltungssystem. Platzieren Sie es nicht in einem Screenshot, Ticket oder freigegebenen Dokument.
Schritt 2: Den GHE.com-Mandanten in Apidog konfigurieren
Nur ein Organisationsadministrator kann diese Integration konfigurieren oder löschen.
- Öffnen Sie die Apidog-Organisation.
- Gehen Sie zu **Organisationseinstellungen**.
- Öffnen Sie **GitHub-Integration**.
- Suchen Sie **GitHub Enterprise Cloud Data Residency** und wählen Sie **Konfigurieren**.
- Geben Sie die GHE.com-Host-URL ein, z. B.
https://company.ghe.com. - Wählen Sie **OAuth App** als Authentifizierungsmethode.
- Geben Sie die Client ID der OAuth App ein.
- Geben Sie das Client Secret der OAuth App ein.
- Speichern Sie die Konfiguration.
Konfigurieren Sie den Mandanten-Host und die OAuth App-Anmeldeinformationen auf Organisationsebene.
Nach dem Speichern zeigt Apidog die konfigurierte Host-URL an. Das Client Secret wird nicht erneut angezeigt oder vorab ausgefüllt.
Wenn Sie die Konfiguration später bearbeiten, bleibt das bestehende Secret erhalten, wenn Sie das Feld für das Client Secret leer lassen. Geben Sie einen neuen Wert nur beim Rotieren ein.
Schritt 3: Ein Repository aus einem Apidog-Projekt verbinden
Nachdem die Konfiguration auf Organisationsebene abgeschlossen ist:
- öffnen Sie das gewünschte Apidog-Projekt;
- starten Sie einen Git-Verbindungs- oder Git-Import-Workflow;
- wählen Sie **GitHub Enterprise Cloud**;
- fahren Sie mit der Autorisierungsseite auf dem konfigurierten GHE.com-Mandanten fort;
- melden Sie sich an und autorisieren Sie die OAuth-App;
- wählen Sie die GitHub-Organisation aus;
- wählen Sie das Repository und den Branch aus;
- schließen Sie die Verbindung ab.
Die Autorisierung erfolgt auf dem konfigurierten GHE.com-Mandanten, nicht auf dem Standard-github.com.
Wenn die erwartete Organisation oder das Repository fehlt, überprüfen Sie den Zugriff des GitHub-Kontos und die OAuth App-Autorisierung, bevor Sie die Apidog-Organisationseinstellungen ändern.
Schritt 4: Eine OpenAPI-Datei importieren
Um eine OpenAPI- oder Swagger-Datei aus dem verbundenen Repository zu importieren:
- starten Sie einen Import-Workflow im Apidog-Projekt;
- wählen Sie **OpenAPI/Swagger**;
- wählen Sie **Git Repository**;
- wählen Sie die GitHub-Organisation, das Repository, den Branch und die Datei aus;
- wählen Sie **Weiter**;
- wählen Sie ein bestehendes Zielmodul oder erstellen Sie ein neues;
- schließen Sie den Import ab;
- überprüfen Sie die importierten Endpunkte und Schemata, bevor Sie das Ergebnis akzeptieren.
Wählen Sie das vom Projekt benötigte Repository, den Branch und die Spezifikationsdatei aus.
Verwenden Sie für den ersten Import ein Nicht-Produktionsprojekt, insbesondere wenn das Zielmodul bereits API-Definitionen enthält.
Schritt 5: Den fortlaufenden Synchronisations-Workflow wählen
Die Repository-Verbindung kann verschiedene Workflows unterstützen. Wählen Sie eine einzige Quelle der Wahrheit und dokumentieren Sie diese für das Team.
| Workflow | Anwenden bei | Wichtiges Verhalten |
|---|---|---|
| Manueller Import | Änderungen werden nur auf Anfrage in Apidog übernommen | Jeden Import und jedes Zielmodul überprüfen |
| Geplanter Import | Die Git-Datei bleibt die Quelle und Apidog sollte sie in Intervallen aktualisieren | Wird über den lokalen Client oder einen selbst gehosteten Runner gemäß dem konfigurierten Ausführungsmodus ausgeführt |
| Backup in Git | Apidog-Inhalt sollte in eine Repository-Datei geschrieben werden | Repository, Branch und Zieldateipfad konfigurieren; automatische Backups werden nachts während eines zufällig geplanten Nebenzeitraums ausgeführt |
| Spec-first-Modus | Die Spezifikationsdatei ist die Quelle der Wahrheit und das Team bearbeitet über einen Git-orientierten Workflow | Dieser Modus ist derzeit Beta; die Webhook-Installation erfordert normalerweise Repository-Admin-Berechtigungen |
Konfigurieren Sie keine zwei gegensätzlichen automatisierten Workflows für dieselbe Datei ohne eine klare Konfliktlösungsregel.
Für das Backup:
- erstellen oder wählen Sie die Git-Verbindung in den Projekteinstellungen aus;
- öffnen Sie **Übersicht > API-Spezifikation** des Moduls;
- fügen Sie die OpenAPI-Spezifikation hinzu oder wählen Sie sie aus;
- aktivieren Sie **Backup in Git Repository**;
- wählen Sie die Repository-Verbindung, den Branch und den Zieldateipfad aus;
- speichern Sie die Konfiguration.
Für eine Repository-gesteuerte Quelle der Wahrheit verwenden Sie den Geplanten Import oder prüfen Sie den Spec-first-Modus.
Schritt 6: Die Integration überprüfen
Führen Sie einen kleinen End-to-End-Test durch:
- bestätigen Sie, dass die Autorisierung den konfigurierten GHE.com-Mandanten öffnet
- bestätigen Sie, dass nur die erwarteten Organisationen und Repositories verfügbar sind
- importieren Sie eine bekannte OpenAPI-Datei und vergleichen Sie das Ergebnis mit der Quelle
- testen Sie die ausgewählte Backup- oder Synchronisierungsrichtung in einem temporären Branch
- bestätigen Sie, dass Branch-Schutz und Repository-Berechtigungen wie erwartet funktionieren
- Synchronisierungsprotokolle oder Fehler überprüfen
- das OAuth App Client Secret rotieren und bestätigen, dass der dokumentierte Aktualisierungsprozess funktioniert
Wenn die Webhook-Synchronisierung verwendet wird, überprüfen Sie, ob der Installateur Repository-Admin-Berechtigungen besitzt und dass das erwartete Push-Ereignis die Synchronisierung auslöst.
Organisationseinstellungen aktualisieren oder löschen
Organisationsadministratoren können die Host-URL oder Client ID bearbeiten und das Client Secret durch Eingabe eines neuen Werts rotieren.
Um die Konfiguration auf Organisationsebene zu entfernen, öffnen Sie **Organisationseinstellungen > GitHub-Integration**, suchen Sie die Data-Residency-Integration und wählen Sie **Einstellungen löschen**.
Nach dem Löschen der Einstellungen können Benutzer keine neuen GitHub Enterprise Cloud-Verbindungen erstellen, bis die Integration erneut konfiguriert wird. Bestehende Verbindungen erfordern möglicherweise eine Neukonfiguration oder Reautorisierung, abhängig vom Token-Status und den Organisationseinstellungen.
Fehlerbehebung
| Problem | Was zu prüfen ist |
|---|---|
| Die Integrationsoption ist nicht verfügbar | Bestätigen Sie, dass die Organisation Zugriff auf die Enterprise-Funktion hat und dass Sie ein Organisationsadministrator sind. |
| OAuth gibt einen Callback-Fehler zurück | Bestätigen Sie, dass der OAuth App-Callback exakt https://api.apidog.com/passport/github/callback ist. |
| Die Autorisierung öffnet github.com | Bestätigen Sie, dass der Host auf Organisationsebene der beabsichtigte Stamm-*.ghe.com-Mandant ist. |
| Ein Repository fehlt | Überprüfen Sie den Organisations- und Repository-Zugriff des autorisierten GitHub-Benutzers sowie eventuelle OAuth-Einschränkungen. |
| Ein Projektbenutzer kann keine Verbindung erstellen | Bestätigen Sie, dass der Benutzer die erforderliche Projekt-Level-Git-Verbindungsberechtigung hat. |
| Import oder Synchronisierung schlägt fehl | Überprüfen Sie den ausgewählten Branch, Dateipfad, Dateiformat, Repository-Berechtigungen und Synchronisierungsprotokolle. |
Sicherheits- und Datenresidenzgrenzen
- Nur Organisationsadministratoren können die GHE.com-Integration konfigurieren oder löschen.
- Das Client Secret wird nach der Konfiguration nicht angezeigt.
- Projektberechtigungen steuern weiterhin, wer Git-Verbindungen erstellen oder aktualisieren kann.
- Die OAuth-Autorisierung erfolgt über den konfigurierten GHE.com-Mandanten.
- Angeforderte OAuth-Berechtigungen können den Zugriff umfassen, der zum Lesen von Organisationen, Repositories, Branches, Importieren von Dateien, Schreiben von Backups und Verwalten von Repository-Hooks erforderlich ist, wenn dies durch einen Synchronisations-Workflow verlangt wird.
Die Verbindung eines Data-Residency-Mandanten beweist nicht per se, dass jede Kategorie von GitHub- oder Apidog-bezogenen Daten in einer Region verbleibt. GitHub dokumentiert die von seinem Residenzangebot abgedeckten Daten und relevante Ausnahmen. Apidog ist ein separater verbundener Dienst mit einem eigenen Speicher- und Bereitstellungsmodell. Überprüfen Sie die aktuelle Dokumentation beider Anbieter als Teil einer Datenresidenz- oder Compliance-Bewertung.
Verwandte Tutorials zur API-Governance:
Diese Tutorials behandeln ergänzende Kontrollen zur Verwaltung eines Enterprise-API-Arbeitsbereichs:
- API Governance Framework — verbindet Eigentum, Kontrollen, Nachweise und Lebenszyklusentscheidungen.
- SAML-Gruppen-Mapping mit Microsoft Entra ID — weist Teamzugriff aus Identitätsanbietergruppen zu.
- Secret Scanner — überprüft mögliche offengelegte Anmeldeinformationen in unterstützten Apidog-Assets.
- Audit-Protokolle — administrative Organisationsaktivitäten untersuchen und exportieren.
- SCIM-Provisioning — Organisationsbenutzer über den Identitätslebenszyklus verwalten.
- Enterprise-Richtlinien — konfigurieren Sie Anmeldeinformationen, Mitgliedschaft, SSO-Sitzung und Einladungskontrollen.
- Self-Service API-Teams — erlauben Sie von Mitgliedern erstellte Teams, während die Eigentumsaufsicht erhalten bleibt.
- GitHub Enterprise Cloud Integration — verbindet unterstützte GHE.com-Repositories für OpenAPI-Workflows.
Verwandte offizielle Dokumentation: