Git-Mirror-Repositories einrichten und synchron halten

1. Wozu Mirror-Repositories gebraucht werden

Ein Mirror-Repository dient in erster Linie als vollständige, exakte Kopie eines bestehenden Repositories, üblicherweise auf einem anderen Server oder einer anderen Plattform. Der naheliegendste Einsatzzweck ist ein regelmäßiges Backup, das im Fall eines Ausfalls oder Datenverlusts des primären Git-Servers eine vollständige Wiederherstellung erlaubt, ohne auf einzelne Snapshots des Dateisystems angewiesen zu sein.

Ein zweiter häufiger Einsatzzweck ist die Migration zwischen zwei Hosting-Plattformen, etwa von einer selbst gehosteten GitLab-Instanz zu GitHub oder umgekehrt: Der Mirror hält beide Seiten während einer Übergangsphase synchron, bis das Team endgültig auf die neue Plattform umgestellt hat. Auch aus Compliance-Gründen wird gelegentlich ein interner Spiegel eines extern gehosteten Repositories verlangt, etwa weil unternehmensinterne Vorgaben verlangen, dass eine vollständige Kopie sämtlichen Quellcodes zusätzlich innerhalb der eigenen Infrastruktur vorgehalten wird, unabhängig davon, wo die eigentliche Zusammenarbeit stattfindet.

2. Der Unterschied zwischen --bare und --mirror beim Klonen

Ein Klon mit --bare erzeugt ein Repository ohne Working Directory, übernimmt dabei aber standardmäßig nur die Standard-Refspec, also im Wesentlichen die Branches, nicht zwangsläufig alle internen Referenzen wie Notes oder sämtliche Remote-Tracking-Branches der Quelle.

Ein Klon mit --mirror geht einen Schritt weiter: Er übernimmt ebenfalls keinen Working Tree, konfiguriert aber zusätzlich automatisch eine erweiterte Refspec, die wirklich jede Referenz aus der Quelle spiegelt, einschließlich aller Branches, Tags, Notes und Remote-Tracking-Referenzen. Für einen vollständigen, verlässlichen Spiegel ist --mirror deshalb die richtige Wahl, nicht --bare.

# Vollständigen Mirror-Klon der Quelle erzeugen
git clone --mirror https://git.quelle.example/projekt.git

3. Ein Mirror-Repository initial erstellen

Der erste Schritt ist der Mirror-Klon der Quelle, wodurch ein lokales bare Repository mit allen Referenzen entsteht. Anschließend wird ein neues, leeres Repository auf der Zielplattform angelegt und als zusätzliches Remote in genau diesem lokalen Mirror-Klon eingetragen.

Mit git push --mirror gegen dieses neue Remote werden anschließend sämtliche Referenzen, also alle Branches und Tags, unverändert in das Ziel-Repository übertragen, wodurch die Zielplattform von Anfang an exakt denselben Stand wie die Quelle erhält.

cd projekt.git
git remote add ziel https://git.ziel.example/projekt.git
git push --mirror ziel

4. Den Mirror aktuell halten mit fetch und push

Für die laufende Synchronisation reicht ein git remote update, das alle konfigurierten Refspecs des lokalen Mirror-Klons neu abholt und dabei sowohl neue Commits als auch neue oder gelöschte Branches und Tags berücksichtigt.

Direkt danach überträgt ein erneutes git push --mirror gegen das Ziel-Remote genau diesen aktualisierten Stand vollständig weiter, sodass Quelle und Ziel nach jedem Synchronisationslauf wieder exakt übereinstimmen, inklusive zwischenzeitlich gelöschter Referenzen.

cd projekt.git
git remote update
git push --mirror ziel

5. Synchronisation automatisieren mit Cronjob oder CI-Schedule

In der Praxis läuft dieser Zwei-Schritt-Ablauf üblicherweise nicht manuell, sondern über einen periodischen Cronjob, der alle paar Minuten oder Stunden fetch und push nacheinander ausführt, oder alternativ über eine geplante CI-Pipeline, die dasselbe Skript auf einem eigenen Zeitplan aufruft.

Wichtig für eine belastbare Automatisierung ist eine saubere Fehlerbehandlung: Schlägt der fetch etwa wegen eines vorübergehenden Netzwerkausfalls fehl, sollte der nachfolgende push in diesem Lauf nicht mehr ausgeführt werden, um niemals einen veralteten, nur teilweise aktualisierten Stand ins Ziel-Repository zu übertragen.

#!/bin/bash
set -e
cd /srv/mirrors/projekt.git
git remote update
git push --mirror ziel

6. Force-Push und gelöschte Branches im Mirror korrekt abbilden

git push --mirror überschreibt das Ziel-Repository exakt nach dem Stand des lokalen Mirror-Klons, einschließlich zwischenzeitlich gelöschter Branches und Tags, die dabei auch im Ziel-Repository entfernt werden. Das ist beabsichtigtes Verhalten für einen echten Spiegel, kann bei einer fehlerhaften Konfiguration aber genauso echte Daten im Ziel-Repository unwiederbringlich löschen.

Aus diesem Grund sollte ein Ziel-Repository, das per Mirror-Push befüllt wird, niemals gleichzeitig von Menschen direkt beschrieben werden. Jede manuelle Änderung im Ziel, die nicht auch in der Quelle existiert, geht beim nächsten automatisierten Synchronisationslauf ersatzlos verloren.

7. Mirror als Zwischenschritt bei einer Plattform-Migration

Bei einer geplanten Migration, etwa von GitLab zu GitHub, hält ein regelmäßig laufender Mirror beide Plattformen während der gesamten Übergangsphase synchron, während das Team weiterhin gewohnt gegen die alte Plattform arbeitet. Das reduziert das Risiko eines abrupten Umstiegs erheblich, da jederzeit ein vollständiger, aktueller Stand auf der neuen Plattform vorliegt.

Der eigentliche Umstieg erfolgt dann nicht technisch, sondern organisatorisch: Sobald das Team bereit ist, wird die alte Plattform schreibgeschützt gesetzt, ein letzter finaler Synchronisationslauf durchgeführt, und anschließend die Standard-Remote-URL im lokalen Setup jedes Teammitglieds auf die neue Plattform umgestellt. In dieser Übergangsphase lohnt sich zusätzlich eine kurze, für alle sichtbare Notiz in beiden Plattformen, welche Seite gerade als verbindliche Quelle gilt, damit niemand versehentlich noch gegen die bald abzuschaltende alte Plattform arbeitet, während der Mirror bereits im Hintergrund synchronisiert.

8. Push-Mirroring gegenüber eingebautem Pull-Mirroring der Plattformen

GitLab bietet in den Projekteinstellungen ein natives Pull-Mirroring an, bei dem GitLab selbst in konfigurierbaren Intervallen von einer externen Quelle abholt, ohne dass ein eigener Cronjob oder eine eigene Pipeline dafür betrieben werden muss. GitHub bietet eine vergleichbare Funktion nicht direkt in den Bordmitteln an, lässt sich aber über eine geplante GitHub Action mit demselben fetch-und-push-Ablauf nachbilden.

Der Unterschied zum manuellen CLI-Ansatz liegt vor allem in der Kontrolle: Natives Plattform-Mirroring ist bequemer, macht aber vollständig von der jeweiligen Plattformfunktion abhängig, während ein eigenes Skript unabhängig von beiden beteiligten Plattformen läuft und sich frei um zusätzliche Prüfungen wie Benachrichtigungen bei fehlgeschlagener Synchronisation erweitern lässt.

9. Mirror-Status überwachen und Inkonsistenzen erkennen

Ein einfacher, aber wirksamer Prüfschritt vergleicht die Ausgabe von git ls-remote für Quelle und Ziel: Stimmen die Listen der Referenzen und der dazugehörigen Commit-Hashes überein, war die letzte Synchronisation erfolgreich, andernfalls deutet eine Abweichung auf einen fehlgeschlagenen oder unvollständigen Lauf hin.

In einer produktiv genutzten Automatisierung gehört zu einem solchen Vergleich zusätzlich eine Alarmierung, etwa per E-Mail oder Chat-Benachrichtigung, sobald zwei aufeinanderfolgende Synchronisationsläufe fehlschlagen, damit ein veralteter Mirror nicht unbemerkt über einen längeren Zeitraum bestehen bleibt. Ergänzend bietet sich eine kurze Protokolldatei an, die Zeitpunkt und Ergebnis jedes einzelnen Laufs festhält, sodass sich im Fall einer Störung sofort nachvollziehen lässt, seit wann genau die Abweichung zwischen Quelle und Ziel tatsächlich besteht.

# Referenzlisten von Quelle und Ziel vergleichen
diff <(git ls-remote https://git.quelle.example/projekt.git) \
     <(git ls-remote https://git.ziel.example/projekt.git)

10. Zusammenfassung

11. FAQ: Git-Mirror-Repositories