Migration von GitLab.com zu selbst gehostetem GitLab
Wenn ein Team von GitLab.com auf eine eigene Instanz umzieht, ist der Code nur ein Teil der Aufgabe. Auch Issues, Merge Requests, Labels, Meilensteine und deren Verlauf müssen mitziehen, am besten ohne manuelles Kopieren.
GitLab hat dafür eine integrierte Methode namens Direct Transfer. Ihre Instanz verbindet sich per HTTPS mit einem Personal Access Token mit GitLab.com und kopiert eine Gruppe samt ihren Projekten. Der Import läuft im Hintergrund, und nach Abschluss können Sie jedes migrierte Element prüfen.
Diese Anleitung zeigt die vollständige Migration einer Gruppe: GitLab.com vorbereiten, den Import starten, das Ergebnis prüfen und die Schritte abschließen, die Direct Transfer nicht abdeckt. Alle Schritte wurden bei einer echten Migration von GitLab.com auf GitLab 19.5 unter Ubuntu 26.04 getestet.
Voraussetzungen für die Migration
Eine selbst gehostete GitLab-Instanz, die installiert ist und läuft. Falls Sie noch keine haben, installieren Sie sie zuerst, siehe die Anleitung GitLab auf einem Dedicated Server installieren.
Administratorzugriff auf Ihre GitLab-Instanz.
Die Rolle Owner in der Gruppe, die Sie auf GitLab.com migrieren möchten. Die Importseite listet nur Gruppen auf, in denen Sie Owner sind.
Ausgehender HTTPS-Zugriff von Ihrem Server auf https://gitlab.com.
Genügend freier Speicherplatz auf dem Server für alle zu migrierenden Repositories sowie freier Platz in /tmp: GitLab entpackt dort temporäre Migrationsarchive.
GitLab.com läuft immer mit einer neueren Version als eine selbst gehostete Instanz. In unserem Test hat das die Migration nicht verhindert.
Ersetzen Sie in dieser Anleitung durchgehend gitlab.example.com durch die Domain Ihrer Instanz.
Was migriert wird
Direct Transfer überträgt:
- die Gruppe und ihre Projekte;
- Repositories mit allen Branches und dem Commit-Verlauf, die Commit-Hashes bleiben gleich;
- Issues und Merge Requests mit ihren ursprünglichen Nummern;
- Labels, Meilensteine und den Aktivitätsverlauf;
- die ursprünglichen Erstellungsdaten.
Importierte Beiträge und einige Mitgliedschaften werden zunächst Platzhalter-Benutzern zugeordnet. Nach dem Import weisen Sie sie echten Konten auf Ihrer Instanz zu.
Direct Transfer überträgt nicht:
- CI/CD-Variablen, Variablen von Pipeline-Zeitplänen und Pipeline-Trigger;
- Deploy Keys und Deploy Tokens;
- Container-Registry-Images und die Package Registry;
- CI/CD-Job-Logs und Job-Artefakte;
- Webhooks;
- Umgebungen und Feature Flags;
- Genehmigungsregeln für Merge Requests und verknüpfte Issues;
- Remote-Mirrors.
Pipelines werden als Datensätze mit ihrem Status migriert, jedoch ohne Job-Logs und Artefakte.
Planen Sie vor dem Start, wie Sie diese Elemente wiederherstellen. CI/CD-Variablen, Deploy Keys und Deploy Tokens enthalten oft Passwörter und API-Schlüssel, daher legen Sie sie nach dem Import manuell neu an. Container-Images und Pakete werden nicht kopiert: Übertragen Sie sie erneut auf Ihre Instanz oder bauen Sie sie mit CI neu.
GitLab.com-Konto vorbereiten
E-Mail-Adresse öffentlich machen. Wählen Sie auf GitLab.com oben rechts Ihren Avatar und dann Edit profile. Wählen Sie unter Public email Ihre E-Mail-Adresse aus und wählen Sie unten auf der Seite Update profile settings.
Personal Access Token erstellen. Ihre Instanz verwendet dieses Token, um Ihre Daten auf GitLab.com zu lesen. Gehen Sie im linken Menü Ihres Profils zu Access > Personal access tokens.
Wählen Sie Generate token und dann Legacy token.
Füllen Sie das Formular aus:
- Token name: ein beliebiger Name, zum Beispiel
migration. - Expiration date: Für die Migration genügen ein paar Tage.
- Select scopes: Wählen Sie
api. Verwechseln Sie es nicht mitread_api.
Wählen Sie Generate token. Kopieren Sie das Token, es beginnt mit glpat-, und speichern Sie es an einem sicheren Ort. GitLab.com zeigt es nur ein einziges Mal an.
Senden Sie das Token nicht in Chats oder E-Mails. Wer es besitzt, erhält vollen API-Zugriff auf Ihr GitLab.com-Konto, bis das Token abläuft oder widerrufen wird.
Direct Transfer auf Ihrer Instanz aktivieren
Melden Sie sich als Administrator bei Ihrer GitLab-Instanz an. Wählen Sie oben rechts Admin, gehen Sie zu Settings > General und erweitern Sie Import and export settings. Aktivieren Sie unter Allow migrating GitLab groups and projects by direct transfer das Kontrollkästchen Enabled und wählen Sie Save changes.
Prüfen Sie im selben Abschnitt zwei Einstellungen, die sich auf die Neuzuweisung von Benutzern nach dem Import auswirken:
- Allow contribution mapping to administrators: Wenn aktiviert, können Sie Beiträge auch Administratorkonten zuweisen;
- Skip confirmation when administrators reassign placeholder users: Wenn aktiviert, werden Beiträge sofort und ohne Zustimmung des Benutzers neu zugewiesen.
Instanz mit GitLab.com verbinden
Wählen Sie in der oberen Leiste Create new (das Plus-Symbol), dann New group > Import group.
Füllen Sie das Verbindungsformular aus:
- GitLab source instance base URL:
https://gitlab.com - Personal access token: das Token, das Sie auf GitLab.com erstellt haben.
Wählen Sie Connect instance.
Die Seite Import groups by direct transfer öffnet sich mit einer Liste Ihrer Gruppen auf GitLab.com.
Import starten
Suchen Sie die Gruppe in der Liste. Öffnen Sie unter Path of the new group die Auswahl Select parent group und legen Sie fest, wo die Gruppe platziert wird:
- No parent erstellt eine Gruppe der obersten Ebene, genau wie auf GitLab.com;
- eine bestehende Gruppe auf Ihrer Instanz importiert die Gruppe als Untergruppe. Ist die übergeordnete Gruppe privat, werden öffentliche Gruppen und Projekte von GitLab.com nach dem Import privat.
Diese Auswahl ist erforderlich. Solange Sie keine übergeordnete Gruppe wählen, zeigt GitLab Select a parent group an und startet den Import nicht.
Prüfen Sie den Pfad der neuen Gruppe, standardmäßig entspricht er dem Namen auf GitLab.com. Lassen Sie Import user memberships ausgewählt, damit die Gruppenmitglieder übernommen werden.
Ändern Sie die Gruppe und ihre Projekte auf GitLab.com nicht mehr, nachdem der Import gestartet wurde. Änderungen während der Migration erreichen Ihre Instanz möglicherweise nicht. Bitten Sie das Team, bis zum Abschluss des Imports keinen Code mehr zu pushen und keine Issues zu bearbeiten.
Wählen Sie in der Zeile der Gruppe Import with projects. Der Status wechselt zu Importing.
Wenn die Schaltfläche Import with projects fehlt, prüfen Sie Default minimum role required to create projects unter Admin > Settings > General > Visibility and access controls. Ist dort No one eingestellt, kann GitLab keine Projekte importieren.
Der Import läuft im Hintergrund, Sie können die Seite also schließen. Die Dauer hängt von Anzahl und Größe der Projekte ab: In unserem Test dauerte eine Gruppe mit zwei kleinen Projekten etwa zwei Minuten.
Ergebnis prüfen
Wenn der Import abgeschlossen ist, wechselt der Status zu Complete.
Lautet der Status Failed oder Partially completed, wählen Sie Show errors, um zu sehen, welche Elemente nicht importiert wurden. Eine fehlgeschlagene oder teilweise Migration können Sie auf derselben Seite oder über die API wiederholen.
Wählen Sie Migration details. Die Seite Migration history zeigt die Gruppe und jedes Projekt mit eigenem Status.
Öffnen Sie die importierte Gruppe und prüfen Sie ihren Inhalt.
Projekte. Alle Projekte der Gruppe müssen in der Liste stehen.
Issues und Merge Requests. Öffnen Sie im Gruppenmenü Work items und Merge requests. Nummern, Labels und Meilensteine bleiben erhalten, und die importierten Elemente tragen das Badge Imported.
Repository. Gehen Sie in einem Projekt zu Code > Branches. Prüfen Sie, ob alle erwarteten Branches vorhanden sind und ihre neuesten Commits mit dem Quell-Repository übereinstimmen.
Die Autoren von Issues und Merge Requests werden als Placeholder users angezeigt, zum Beispiel Placeholder John Smith. Das ist erwartet, Sie weisen sie später in dieser Anleitung neu zu.
Wenn ein Merge Request Cannot be merged automatically anzeigt, öffnen Sie ihn und prüfen Sie den Tab Changes. Zeigt er keine Änderungen, hatte der Merge Request auch auf GitLab.com keine Commits, es gibt also nichts zu mergen. Das ist kein Migrationsfehler.
CI/CD-Variablen neu anlegen
Öffnen Sie auf GitLab.com das Projekt, gehen Sie zu Settings > CI/CD, erweitern Sie Variables und notieren Sie jede Variable mit ihren Optionen, zum Beispiel Protected und Masked.
Öffnen Sie auf Ihrer Instanz dasselbe Projekt und denselben Abschnitt. Die Liste der Projektvariablen ist leer.
Wählen Sie Add variable und legen Sie jede Variable mit demselben Schlüssel, Wert und denselben Optionen an. Wiederholen Sie das für Gruppenvariablen, falls Sie welche verwenden.
Pipeline-Zeitpläne werden ohne ihre Variablen migriert. Wenn Ihre Zeitpläne Variablen verwenden, öffnen Sie im Projekt Build > Pipeline schedules und fügen Sie sie jedem Zeitplan hinzu.
Platzhalter-Benutzer neu zuweisen
Beim Import erstellt GitLab Platzhalter-Benutzer für die Autoren von Beiträgen und für importierte Mitglieder von GitLab.com. Um deren Issues, Merge Requests und Kommentare echten Konten zuzuordnen, weisen Sie die Platzhalter neu zu. Legen Sie zuerst die Konten Ihres Teams auf der Instanz an, damit es Ziele für die Zuweisung gibt.
Öffnen Sie die Gruppe der obersten Ebene, also die importierte Gruppe selbst oder deren übergeordnete Gruppe, falls Sie sie als Untergruppe importiert haben, gehen Sie zu Manage > Members und wählen Sie den Tab Placeholders. Sie benötigen die Rolle Owner in dieser Gruppe. Die Liste Awaiting reassignment zeigt alle Platzhalter-Benutzer.
Öffnen Sie in der Zeile eines Platzhalters Select user und wählen Sie das Konto auf Ihrer Instanz. Prüfen Sie, ob in der richtigen Zeile das richtige Konto ausgewählt ist, und wählen Sie dann Reassign und Confirm reassignment.
Die Neuzuweisung kann nicht rückgängig gemacht werden. Eine falsche Auswahl gibt die Beiträge und den Zugriff einer Person einem anderen Benutzer, prüfen Sie daher jede Zeile, bevor Sie bestätigen.
Der Status wechselt zu Reassigning. Aktualisieren Sie die Seite nach einer Minute: Der Platzhalter wandert in den Tab Reassigned.
Das Issue zeigt nun das echte Konto als Autor, und das ursprüngliche Erstellungsdatum bleibt erhalten.
Ist Skip confirmation when administrators reassign placeholder users aktiviert, wie auf unserer Testinstanz, werden Beiträge sofort neu zugewiesen. Ist die Option deaktiviert, muss der ausgewählte Benutzer die Neuzuweisung zuerst annehmen.
Dienstkonten von GitLab.com, zum Beispiel Duo Code Review, kommen ebenfalls als Platzhalter an. Sie haben keine Entsprechung auf Ihrer Instanz: Lassen Sie sie unverändert oder wählen Sie Do not reassign. Für viele Benutzer verwenden Sie Reassign with CSV file im selben Tab.
Migration abschließen
Token widerrufen. Gehen Sie auf GitLab.com zu Access > Personal access tokens und wählen Sie neben dem Migrations-Token Revoke.
Remote-Adresse auf Entwicklerrechnern aktualisieren. Richten Sie Git in jeder lokalen Kopie eines Repositorys auf Ihre Instanz aus:
git remote set-url origin [email protected]:group/project.git
Ersetzen Sie group/project durch den Pfad des Projekts auf Ihrer Instanz.
Integrationen und Automatisierung neu einrichten. Webhooks, Deploy Keys, Deploy Tokens und Pipeline-Trigger werden nicht migriert, legen Sie sie daher auf Ihrer Instanz neu an. Registrieren Sie CI/CD-Runner bei Ihrer Instanz. Verbinden Sie externe Dienste, etwa Chat-Benachrichtigungen oder Issue-Tracker, in den Einstellungen jedes Projekts neu.
Neue Pipelines für importierte Merge Requests ausführen. Importierte Pipelines behalten ihren ursprünglichen Status und können Pipelines must succeed erfüllen, ohne erneut zu laufen. Führen Sie vor dem Merge eines importierten Merge Requests auf Ihrer Instanz eine neue Pipeline dafür aus.
Alte Kopie schließen. Wenn auf Ihrer Instanz alles funktioniert, archivieren oder löschen Sie die Gruppe auf GitLab.com, damit dort niemand weiterarbeitet.
Informationen zur Wahl eines Servers für Ihre GitLab-Instanz finden Sie auf der Seite Dedicated Server für GitLab.
