Wie verbindet man Apidog mit GitHub und GitLab

Wenn Ihre API-Spezifikationen in Apidog liegen, Ihre „Source of Truth“ aber in Git, sollten beide dauerhaft synchron bleiben. Die Apidog Git-Integration verbindet Ihr Apidog-Projekt mit GitHub, GitLab oder Azure DevOps, überträgt OpenAPI-Spezifikationen in die Versionskontrolle und holt Repository-Änderungen zurück nach Apidog. So erhalten Sie nachvollziehbare Historie, Code-Review für Spezifikationsänderungen und ein Git-Backup Ihrer API-Verträge.

Teste Apidog noch heute

Dieser Leitfaden zeigt, wie Sie die Integration praktisch einrichten und im Team nutzen: Anbieter verbinden, Repository und Branch auswählen, OpenAPI-Dateien im Spec-First-Modus synchronisieren, automatische Backups konfigurieren und typische Fehler beheben. Wenn Sie nur GitHub verwenden, lesen Sie zusätzlich den fokussierten Leitfaden zum Synchronisieren Ihrer OpenAPI-Spezifikation mit GitHub.

Was die Apidog Git-Integration leistet

Apidog arbeitet auf zwei Arten mit Git. Beide lösen unterschiedliche Probleme:

1. Bidirektionale Synchronisierung im Spec-First-Modus

   • Sie bearbeiten OpenAPI als YAML oder JSON in Apidog.
   • Sie committen und pushen Änderungen in Git.
   • Sie pullen Änderungen aus dem Repository zurück nach Apidog.

2. Automatische Git-Sicherung

   • Apidog exportiert OpenAPI/Swagger-Dateien automatisch.
   • Der Export wird geplant in ein Repository gepusht.
   • Änderungen aus Git werden dabei nicht zurück nach Apidog gelesen.

Funktion	Richtung	Auslöser	Geeignet für
Spec-First-Modus-Synchronisierung	Bidirektional: Push und Pull	Manuelles Commit/Push, manueller Pull	Teams, die API-Spezifikationen wie Code behandeln
Automatische Git-Sicherung	Unidirektional: Apidog → Git	Geplant, außerhalb der Spitzenzeiten	Teams, die ein versioniertes Backup ohne Workflow-Änderung benötigen

Merken Sie sich die Unterscheidung:

• Synchronisierung bedeutet: bidirektionaler Spec-First-Workflow.
• Backup bedeutet: geplanter, unidirektionaler Export.

Unterstützte Git-Anbieter

Apidog unterstützt GitHub, GitLab und Azure DevOps.

Anbieter	Authentifizierung	Hinweise
GitHub	OAuth über GitHub-Login	Funktioniert mit persönlichen und Organisations-Repositories. Organisations-Repositories benötigen ggf. Admin-Genehmigung.
GitLab	OAuth über GitLab-Login	Unterstützt gitlab.com und erreichbare selbstverwaltete GitLab-Instanzen.
Azure DevOps	Generische Git-Verbindung über HTTPS + Token	Verbindung über HTTPS-Repo-URL und Personal Access Token mit Repo-Berechtigung.

Die generische Git-Verbindung ist nützlich, wenn Ihr Git-Host nicht direkt als GitHub oder GitLab angebunden ist, aber Git über HTTPS und Token-Authentifizierung unterstützt. Azure DevOps ist der häufigste Fall.

Git-Anbieter verbinden

Der Ablauf ist bei allen Anbietern ähnlich:

1. Anbieter autorisieren.
2. Repository auswählen.
3. Branch auswählen.
4. Projekt mit Repository und Branch verbinden.
5. Synchronisierung oder Backup konfigurieren.

GitHub verbinden

Für GitHub verwenden Sie den OAuth-Flow:

1. Öffnen Sie in Apidog die Git-Integration.
2. Wählen Sie GitHub aus.
3. Melden Sie sich bei GitHub an.
4. Gewähren Sie Apidog Zugriff auf die benötigten Repositories.
5. Wählen Sie Repository und Branch aus.

Bei Organisations-Repositories kann GitHub eine zusätzliche Admin-Genehmigung verlangen. Wenn die Autorisierung erfolgreich wirkt, das Repository aber nicht angezeigt wird, fehlt häufig diese Genehmigung.

GitLab verbinden

Für GitLab ist der Ablauf ähnlich:

1. Wählen Sie GitLab als Anbieter.
2. Melden Sie sich über OAuth an.
3. Gewähren Sie Repository-Zugriff.
4. Wählen Sie Repository und Branch.

Selbstverwaltetes GitLab funktioniert, wenn Apidog die Instanz über das Netzwerk erreichen kann.

Azure DevOps verbinden

Für Azure DevOps verwenden Sie die generische Git-Verbindung:

1. Kopieren Sie die HTTPS-Klon-URL Ihres Repositories.
2. Erstellen Sie in Azure DevOps ein Personal Access Token.
3. Geben Sie dem Token Lese- und Schreibzugriff auf Code.
4. Fügen Sie URL und Token in Apidog ein.
5. Wählen Sie den gewünschten Branch.

Begrenzen Sie das Token auf die benötigten Projekte oder Repositories. Verwenden Sie kein Token mit unnötig breiten Kontorechten.

Berechtigungen prüfen

Achten Sie vor dem ersten Push auf diese Punkte:

• Private Repositories sind möglich, solange die Autorisierung korrekt ist.
• Organisationen benötigen ggf. Admin-Freigabe für Drittanbieterzugriff.
• PATs sollten minimal berechtigt sein, idealerweise nur für das Ziel-Repository.
• Schreibrechte sind erforderlich, wenn Apidog Commits pushen soll.

Wenn Sie den Git-Workflow grundsätzlich strukturieren möchten, lesen Sie den Leitfaden zur OpenAPI-Versionskontrolle mit Git.

Bidirektionale Synchronisierung mit dem Spec-First-Modus

Der Spec-First-Modus ist der Workflow für Teams, die OpenAPI-Dateien wie Code behandeln. Sie bearbeiten die Spezifikation in Apidog, committen die Änderung und pushen sie in Git. Änderungen aus Git können Sie zurück nach Apidog pullen.

Die offizielle Referenz finden Sie in der Apidog-Dokumentation zum Spec-First-Modus.

Typischer Workflow

1. OpenAPI-Dokument in Apidog öffnen.
2. YAML oder JSON bearbeiten.
3. Validierung prüfen.
4. Änderung committen.
5. In den verbundenen Branch pushen.
6. Bei Änderungen im Repository: pullen und erneut synchronisieren.

Beispiel für eine Änderung an einer OpenAPI-Spezifikation:

paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve a single order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

Nach dem Speichern erkennt Apidog die Änderung als lokale Bearbeitung. Danach committen Sie mit einer Nachricht und pushen in den verbundenen Branch.

Beispiel für sinnvolle Commit-Messages:

Add getOrder endpoint
Update Order schema response fields
Fix missing required parameter in order path

Nach erfolgreichem Push zeigt Apidog einen Synchronisierungsstatus wie „Gerade synchronisiert“ an. Das bedeutet: Apidog und der verbundene Branch enthalten denselben Stand.

Änderungen aus Git zurückholen

Wenn ein Teammitglied die OpenAPI-Datei direkt im Repository ändert, holen Sie diese Änderung nach Apidog zurück:

1. In Apidog den Pull/Synchronisierungsstatus prüfen.
2. Repository-Änderungen pullen.
3. Spezifikation validieren.
4. Bei Bedarf lokal weiterbearbeiten.
5. Neue Änderungen committen und pushen.

Damit wird Git nicht nur zum Backup-Ziel, sondern bleibt ein gleichwertiger Teil des Workflows.

Nicht gepushte Änderungen verwerfen

Wenn Sie experimentelle Änderungen nicht übernehmen möchten, verwerfen Sie nicht gepushte Bearbeitungen. Dadurch springt Ihre Arbeitskopie auf den letzten synchronisierten Zustand zurück.

Das ist hilfreich, wenn Sie zum Beispiel ein neues Schema testen, aber nicht in Git übernehmen wollen.

Der Ablauf passt zu einem Git-nativen API-Workflow: Spezifikationsänderungen laufen über Commits, Pull Requests, Reviews und Rollbacks wie normale Codeänderungen.

Automatische Git-Sicherung von API-Spezifikationen

Die automatische Git-Sicherung ist für Teams gedacht, die ein versioniertes Backup ihrer API-Spezifikationen möchten, ohne den täglichen Workflow zu ändern.

Dabei exportiert Apidog die OpenAPI/Swagger-Datei eines Moduls und pusht sie automatisch in ein Git-Repository.

So funktioniert das Backup

1. Sie wählen ein Modul in Apidog aus.
2. Sie konfigurieren Repository und Branch.
3. Apidog exportiert die OpenAPI/Swagger-Datei.
4. Der Export wird automatisch in Git committet.
5. Der Push erfolgt in einem zufälligen nächtlichen Zeitfenster außerhalb der Spitzenzeiten.

Jeder Push erzeugt einen Commit. Dadurch können Sie später nachvollziehen:

• wann sich ein API-Vertrag geändert hat,
• welche Felder hinzugefügt oder entfernt wurden,
• welche Version letzte Woche aktiv war,
• welche frühere Version Sie wiederherstellen möchten.

Wichtig: Das Backup ist unidirektional. Apidog schreibt nach Git, liest aber keine Repository-Änderungen zurück. Wenn Sie Änderungen aus Git nach Apidog holen möchten, verwenden Sie den Spec-First-Modus.

Branch und Repository-Struktur auswählen

Die wichtigsten Strukturentscheidungen sind:

• Welcher Branch wird verwendet?
• Liegen Spezifikationen in einem oder mehreren Repositories?
• Wie werden Module im Repository abgelegt?

Branch wählen

Für viele Teams funktioniert dieses Modell:

• main enthält die kanonische, freigegebene Spezifikation.
• Feature-Branches enthalten laufende API-Designänderungen.
• Pull Requests werden für Review und Freigabe genutzt.

Beispiel:

main
feature/add-order-endpoint
feature/update-auth-schema
fix/pagination-response

Wenn Sie Apidog direkt mit main verbinden, ist der Workflow einfacher, aber weniger kontrolliert. Für kleine Teams oder risikoarme Änderungen kann das reichen. Für produktive APIs ist ein Feature-Branch mit Pull Request meistens robuster.

Repository-Modell wählen

Sie haben zwei typische Optionen.

Option 1: Ein Repository pro API

Vorteile:

• saubere Historie pro API,
• klare Zuständigkeiten,
• einfache Zugriffskontrolle,
• weniger Risiko, dass Teams sich gegenseitig beeinflussen.

Geeignet für Organisationen, in denen verschiedene Teams verschiedene APIs besitzen.

Option 2: Monorepo für alle Spezifikationen

Vorteile:

• zentrale Suche,
• einheitliche Review-Prozesse,
• bessere Übersicht über die gesamte API-Landschaft.

Geeignet für Plattformteams oder Organisationen mit zentralem API-Governance-Modell.

Ein mögliches Layout:

api-specs/
  orders/
    openapi.yaml
  payments/
    openapi.yaml
  users/
    openapi.yaml

Wenn Sie automatische Backups verwenden, geben Sie jedem Modul einen eigenen Pfad. Dadurch bleiben Commits lesbar und Backups überschreiben sich nicht gegenseitig.

Team-Berechtigungen und Zugriff

Die Git-Integration arbeitet mit Repository-Zugriff und sollte entsprechend restriktiv konfiguriert werden.

In Apidog

Legen Sie fest, wer synchronisieren und pushen darf.

Empfehlung:

• API-Owner: Push- und Synchronisierungsrechte
• Entwickler: Leserechte oder eingeschränkte Bearbeitung
• Reviewer: Zugriff auf Git-Pull-Requests
• Externe Mitwirkende: nur notwendige Rechte

Beschränken Sie Push-Rechte auf Personen, die den API-Vertrag aktiv pflegen.

Im Git-Anbieter

Bei GitHub und GitLab hängt der Zugriff an der OAuth-Autorisierung. Bei Azure DevOps und generischen Git-Verbindungen ist das PAT die entscheidende Anmeldeinformation.

Behandeln Sie Tokens wie Secrets:

• nicht in Wikis oder Tickets kopieren,
• nicht in Chat-Tools posten,
• nur minimalen Scope vergeben,
• regelmäßig rotieren,
• bei Teamwechsel sofort widerrufen.

Wenn eine Person das Team verlässt, widerrufen Sie deren Token oder OAuth-Zugriff und autorisieren Sie die Integration mit einem aktiven Konto neu.

Merge-Konflikte und Drift vermeiden

Da Apidog echte Git-Commits erzeugt, gelten die normalen Git-Regeln. Konflikte entstehen, wenn zwei Personen denselben Bereich einer OpenAPI-Datei ändern.

Typisches Szenario:

1. Sie ändern das Order-Schema in Apidog.
2. Ein Teammitglied ändert dasselbe Schema im Repository.
3. Das Teammitglied pusht zuerst.
4. Ihr Push oder Pull erzeugt einen Konflikt.
5. Der Konflikt muss in der YAML-Datei aufgelöst werden.

Konflikte reduzieren

Nutzen Sie diese Arbeitsweise:

1. Vor jeder größeren Änderung pullen.
2. Kleine, fokussierte Änderungen committen.
3. Schemas und Endpunkte nicht unnötig gleichzeitig bearbeiten.
4. Pull Requests für Review verwenden.
5. Nach dem Merge Apidog erneut synchronisieren.

Konflikt auflösen

Ein YAML-Konflikt sieht typischerweise so aus:

<<<<<<< HEAD
type: string
=======
type: integer
>>>>>>> feature/update-order-schema

Lösen Sie den Konflikt, indem Sie den korrekten Inhalt auswählen oder zusammenführen:

type: string

Danach:

1. Konfliktmarker entfernen.
2. OpenAPI-Dokument validieren.
3. Änderung committen.
4. Erneut synchronisieren.

Die Live-Validierung im Apidog-Editor hilft dabei, ungültige OpenAPI-Strukturen früh zu erkennen.

Drift erkennen

Drift bedeutet: Apidog und Repository laufen auseinander. Prüfen Sie deshalb regelmäßig den Synchronisierungsstatus. Wenn nicht „synchronisiert“ angezeigt wird, gibt es wahrscheinlich lokale Änderungen, nicht gepullte Repository-Änderungen oder fehlgeschlagene Pushes.

Fehlerbehebung

Viele Probleme entstehen durch Authentifizierung, Branch-Auswahl oder nicht synchronisierte Änderungen.

Symptom	Wahrscheinliche Ursache	Behebung
Autorisierung schlägt fehl oder Repository wird nicht angezeigt	Organisation hat Drittanbieterzugriff nicht genehmigt oder Token-Scope fehlt	GitHub/GitLab-App durch Admin genehmigen lassen; Azure DevOps PAT mit Code-Lese-/Schreibrechten neu erstellen
Push wird abgelehnt	Token widerrufen, abgelaufen oder ohne Schreibrechte	Anbieter neu autorisieren oder neues PAT in Apidog hinterlegen
Änderungen wurden gepusht, sind aber nicht sichtbar	Falscher Branch verbunden	Verbundenen Branch prüfen und ggf. in den Projekteinstellungen wechseln
Synchronisierung hängt oder „Gerade synchronisiert“ erscheint nicht	Lokale Änderungen sind nicht gepusht oder Pull ist erforderlich	Änderungen committen und pushen; bei Remote-Änderungen zuerst pullen
Merge-Konflikt in der Spezifikation	Zwei Bearbeitungen an denselben Zeilen	YAML-Konflikt auflösen, Dokument validieren, erneut synchronisieren
Backup wurde nicht ausgeführt	Nächtliches Zeitfenster wurde noch nicht erreicht oder Backup-Konfiguration ist falsch	Nächsten Zyklus abwarten; Repository-, Branch- und Modulkonfiguration prüfen
Experimentelle Änderungen sollen weg	Lokale Änderungen wurden noch nicht gepusht	Nicht gepushte Bearbeitungen verwerfen

Wenn ein Problem plötzlich auftritt, prüfen Sie zuerst die Anmeldeinformationen. Ein widerrufenes Token, ein abgelaufener PAT oder eine fehlende Organisationsfreigabe erklärt viele Synchronisierungsfehler.

FAQ

Ist die Synchronisierung unidirektional oder bidirektional?

Beides ist möglich, abhängig von der Funktion.

Der Spec-First-Modus ist bidirektional: Sie pushen Änderungen nach Git und pullen Repository-Änderungen zurück nach Apidog.

Die automatische Sicherung ist unidirektional: Apidog exportiert Spezifikationen nach Git, liest daraus aber keine Änderungen zurück.

Wo werden meine Spezifikationen gespeichert?

In dem Git-Repository, das Sie verbinden.

Im Spec-First-Modus liegt das OpenAPI-Dokument auf dem verbundenen Branch. Bei der automatischen Sicherung wird die exportierte OpenAPI/Swagger-Datei jedes Moduls in das konfigurierte Repository committet.

Mit welchem Branch sollte ich synchronisieren?

Für produktive Teams ist ein Feature-Branch-Workflow sinnvoll:

main
feature/api-change

Verwenden Sie main für die freigegebene Spezifikation und Feature-Branches für Änderungen, die per Pull Request geprüft werden sollen.

Was passiert, wenn mein Token widerrufen wird?

Pushes schlagen fehl, weil Apidog keinen Schreibzugriff mehr hat. Autorisieren Sie GitHub oder GitLab erneut. Für Azure DevOps und generische Git-Verbindungen erstellen Sie ein neues Personal Access Token und aktualisieren es in Apidog.

Wann sollte ich Backup statt Spec-First-Modus verwenden?

Verwenden Sie Backup, wenn Sie nur eine versionierte Kopie Ihrer API-Spezifikationen in Git benötigen.

Verwenden Sie den Spec-First-Modus, wenn Git aktiv Teil Ihres API-Designprozesses sein soll, inklusive Pull Requests, Reviews und bidirektionaler Synchronisierung.

Fazit

Die Apidog Git-Integration bietet zwei praktische Workflows:

• Spec-First-Modus für bidirektionale Synchronisierung, Reviews und Git-native API-Entwicklung.
• Automatische Git-Sicherung für versionierte Backups ohne Änderung des täglichen Workflows.

Beide funktionieren mit GitHub, GitLab und Azure DevOps. Wählen Sie den Workflow nach Ziel aus: Wenn Spezifikationsänderungen denselben Review-Prozess wie Code durchlaufen sollen, nutzen Sie den Spec-First-Modus. Wenn Sie nur eine belastbare Historie und ein Backup benötigen, aktivieren Sie die automatische Sicherung.

Viele Teams kombinieren beides: Spec-First für aktive API-Entwicklung und Backup als zusätzliches Sicherheitsnetz.