Bestehendes GitLab migrieren

Du nutzt bereits GitLab und möchtest zu server.camp umziehen? Das geht – und in beiden Fällen bleiben deine Repositories, Issues und Merge Requests erhalten. Welcher Weg der richtige ist, hängt an genau einer Frage: Liegt dein GitLab heute auf gitlab.com oder auf einem eigenen Server?

Vor dem Umzug: Subscription anlegen

Für beide Wege brauchst du zuerst eine GitLab-Subscription bei server.camp – du kannst GitLab 30 Tage kostenlos testen und die Migration schon in der Testphase durchspielen.

Bei gitlab.com ist der Direct Transfer der von GitLab empfohlene Weg. Ein Backup-Restore wie bei Weg B ist hier nicht möglich: Auf GitLab SaaS bekommst du keinen Zugriff auf Backup-Dateien. Als Alternative gibt es lediglich den dateibasierten Export – der überträgt aber weniger Objekte und ist umständlicher, weshalb GitLab selbst zum Direct Transfer rät.

Der Direct Transfer läuft direkt zwischen den beiden GitLab-Instanzen ab, über HTTPS. Du machst das selbst – von uns brauchst du dafür nichts außer der bereitgestellten Instanz.

• Direct Transfer muss auf beiden Instanzen aktiviert sein. Auf gitlab.com ist er aktiv; in deiner Instanz bei server.camp musst du ihn einmal einschalten (siehe nächster Abschnitt).
• Die Owner-Rolle auf der Quellgruppe, die du migrieren willst
• Ein Personal Access Token mit dem Scope api auf der Quelle (also auf gitlab.com) – auf der Zielseite genügt eine Rolle, die dort Untergruppen anlegen darf

Bei selbst gehosteten Instanzen – und damit auch bei uns – ist der Direct Transfer ab Werk deaktiviert; dasselbe gilt seit GitLab 16.0 für alle Import-Quellen. Du schaltest beides als Admin selbst frei (Details bei GitLab unter Import and export settings):

1. Oben rechts Admin auswählen
2. In der linken Seitenleiste Einstellungen → Allgemein
3. Abschnitt Import- und Export-Einstellungen ausklappen
4. Bei Migration von GitLab-Gruppen und -Projekten per Direct Transfer erlauben das Häkchen setzen
5. Im selben Abschnitt unter Import-Quellen zusätzlich GitLab.com aktivieren

Nach dem Umzug wieder abschalten

Beide Schalter sind Import-Funktionen, die du nach der Migration nicht mehr brauchst. Es ist gute Praxis, sie danach wieder zu deaktivieren.

Der Direct Transfer migriert Gruppen und Projekte – aber keine Benutzerkonten. Benutzerkonten werden bei einer Migration nie angelegt. Wie Issues, Merge Requests und Kommentare trotzdem bei den richtigen Personen landen, hat GitLab mit Version 18.4 geändert: Es gibt kein Abgleichen über Benutzernamen oder E-Mail-Adressen mehr, sondern Platzhalter-Benutzer, die du anschließend den echten Konten zuweist (Post-Migration-Zuordnung).

1. Gruppe importieren – Neue Gruppe → Gruppe importieren, dort die Quell-URL (https://gitlab.com) und deinen Token eintragen. Projekte kommen beim Gruppen-Import mit; einzelne Projekte lassen sich auch separat importieren.
2. Platzhalter entstehen automatisch – für jede Person mit Beiträgen legt GitLab einen Platzhalter-Benutzer an (Platzhalter <Name>). Diese Konten können sich nicht anmelden, nichts auslösen und zählen nicht als Lizenz-Nutzer.
3. Benutzer anlegen – als Admin unter Admin-Bereich → Übersicht → Benutzer, oder du bindest gleich Single Sign-On an. Das darf auch nach dem Import passieren: Du hast Zeit, das Ergebnis erst zu prüfen.
4. Beiträge neu zuweisen – in der Top-Level-Gruppe unter Verwalten → Mitglieder → Platzhalter → Zur Neuzuweisung ausstehend wählst du je Platzhalter den echten Benutzer und klickst Neu zuweisen. Für viele Personen gibt es Mit CSV neu zuweisen: Vorlage herunterladen, Benutzername oder öffentliche E-Mail eintragen, hochladen.
5. Die Betroffenen bestätigen – jede Person erhält eine E-Mail und muss die Zuordnung in GitLab mit Neuzuweisung genehmigen annehmen. Erst dann werden die Beiträge übertragen. Bei späteren Importen aus derselben Quelle in dieselbe Gruppe geht die Zuordnung automatisch.

Immer in eine Gruppe importieren, nie in einen persönlichen Namespace

Importierst du ein Projekt in einen persönlichen Namespace, findet kein Beitrags- und Mitgliedschafts-Mapping statt – alle Beiträge werden dem Eigentümer des Namespace zugeschrieben und lassen sich nachträglich nicht mehr aufteilen. Lege deshalb zuerst eine Gruppe an und importiere dorthin.

Registrierung ist standardmäßig deaktiviert

In deiner Instanz bei server.camp ist die offene Registrierung ab Werk aus. Benutzer legst du als Admin unter Admin-Bereich → Übersicht → Benutzer an – oder du bindest gleich Single Sign-On an und lässt die Konten beim ersten Login automatisch entstehen.

Welche Objekte der Direct Transfer überträgt, listet GitLab unter migrated items auf. Erfahrungsgemäß musst du diese Dinge nach dem Import selbst nachziehen:

Beide Instanzen parallel = doppelte Wahrheit

Solange auf gitlab.com weitergearbeitet wird, entstehen dort Commits, Issues und Kommentare, die der Import nicht nachträglich holt. Lege deshalb einen Stichtag fest, ab dem alle nur noch in die neue Instanz pushen – und setze die alten Projekte danach auf archiviert.

Betreibst du GitLab bislang selbst (Omnibus-Paket, Docker oder Kubernetes), gehen wir den vollständigen Weg: Du erstellst ein Backup, wir spielen es bei uns ein. Das Ergebnis ist eine 1:1-Kopie deiner Instanz – inklusive Benutzer, 2FA-Einstellungen, CI/CD-Variablen, Tokens, Registry und LFS-Objekten.

Vorgehen und Dateien entsprechen der offiziellen GitLab-Anleitung Migrate to a new server.

Wir vereinbaren mit dir einen Zeitraum – idealerweise ein halber Tag –, in dem du auf dein GitLab verzichten kannst und wir das Backup in Ruhe einspielen und prüfen können.

1. Du machst deine Instanz schreibfrei, damit das Backup konsistent ist und danach nichts mehr geschrieben wird.
2. Du erzeugst das Backup und übergibst uns die Dateien – Schritt für Schritt beschrieben unter So erstellst du das Backup.
3. Wir stellen die Daten in deiner neuen Instanz wieder her und prüfen sie – unter anderem mit gitlab-rake gitlab:doctor:secrets und gitlab-rake gitlab:check. Der Secrets-Check ist der eigentliche Erfolgsnachweis: Meldet er Fehler, passt das Schlüsselmaterial nicht zur Datenbank, und wir gehen nicht produktiv, sondern klären das mit dir.
4. Wir geben die Instanz frei, du nimmst sie ab.
5. Du stellst DNS bzw. die Git-Remotes um. Die alte Instanz bleibt abgeschaltet, damit nicht versehentlich in zwei Systeme gepusht wird.

Am Ende brauchen wir im Wesentlichen vier Dateien:

gitlab-secrets.json ist der kritische Teil

Ein Restore ohne die passende gitlab-secrets.json sieht auf den ersten Blick erfolgreich aus – aber alle verschlüsselten Werte in der Datenbank lassen sich dann nicht mehr entschlüsseln. In der Folge müssten 2FA für alle Benutzer, alle CI/CD-Variablen und alle Tokens neu gesetzt werden. Das ist dann kein Umzug mehr, sondern ein Neuaufbau. Sichere die Datei deshalb zuerst.

Warum es vier Dateien sind

Das Backup-Archiv enthält bewusst keine Konfiguration und kein Schlüsselmaterial – genau deshalb kommen gitlab.rb und gitlab-secrets.json separat aus /etc/gitlab dazu. Auch Redis ist nicht im Archiv enthalten, weshalb die offizielle Anleitung den Redis-Dump als eigenen Schritt vorsieht (Redis auf die Platte schreiben, dann dump.rdb mitgeben). Ohne Redis-Dump verlierst du die aktiven Sessions – alle Benutzer müssen sich einmal neu anmelden – und die noch in der Warteschlange liegenden Hintergrund-Jobs. Ein Blocker ist das nicht, sauberer ist es mit.

Im Archiv stecken dagegen: Datenbank, Git-Repositories und LFS-Objekte, Uploads und Anhänge, Wikis, Snippets, CI/CD-Artefakte und Job-Logs, externe Merge-Request-Diffs, Package Registry und Container-Registry-Images, Secure Files, Terraform-States und GitLab-Pages-Inhalte. Beim Weg B kommt also deutlich mehr mit als beim Direct Transfer.

Ein Backup passt nur in genau dieselbe Version und Edition

GitLab formuliert das eindeutig: Ein Backup lässt sich ausschließlich in exakt dieselbe Version und denselben Typ (CE oder EE) einspielen, mit dem es erstellt wurde. Beides müssen wir vor dem Wartungsfenster klären, nicht darin.

• Deine Version ermitteln: Rufe /help in deiner Instanz auf oder führe gitlab-rake gitlab:env:info aus.
• Unsere Zielversion erfragen: Wir hosten aktuell GitLab 19.2, Community Edition. Weil wir Versionen regelmäßig aktualisieren, nennt dir unser Support den genauen Stand zum Zeitpunkt deiner Migration.
• Bist du älter? Dann hebe deine Instanz vor dem Backup entlang des offiziellen Upgrade Path auf unseren Stand. Das ist der bevorzugte Weg: Upgrades laufen so noch auf deinem System und nicht unter Zeitdruck im Wartungsfenster.

Enterprise Edition: bitte früh ansprechen

Kommuniziere uns bitte vorab, falls du die Enterprise-Edition nutzt. Abhängig davon, ob du bei uns die Community-Edition oder die Enterprise-Edition nutzt, entscheidet das frühzeitig über den Ablauf des Ex- und Imports. Grundsätzlich sind aber alle Wege möglich.

Die folgenden Schritte entsprechen der offiziellen Anleitung und gelten für eine Instanz aus dem Linux-Paket (Omnibus). Für Docker und Kubernetes steht die Abweichung weiter unten. Führe sie am Anfang des Wartungsfensters aus, in dieser Reihenfolge.

Schritt 1 – Keine neuen Schreibzugriffe mehr zulassen. Nutzt du Premium oder Ultimate, aktiviere den Wartungsmodus unter Admin-Bereich → Einstellungen → Allgemein.

Schritt 2 – Redis auf die Platte schreiben und die Dienste stoppen. Für das Backup selbst müssen nur noch PostgreSQL und Gitaly laufen:

sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket save && \
  sudo gitlab-ctl stop && \
  sudo gitlab-ctl start postgresql && \
  sudo gitlab-ctl start gitaly

Schritt 3 – Backup erzeugen:

sudo gitlab-backup create

Das Archiv landet in /var/opt/gitlab/backups/ und heißt nach dem Muster <backup-id>_gitlab_backup.tar, also zum Beispiel 1784030400_2026_07_26_19.2.0_gitlab_backup.tar. Der Durchlauf kann bei großen Instanzen Stunden dauern – plane das im Wartungsfenster ein und stelle sicher, dass unter /var/opt/gitlab/backups/ genug freier Platz für das komplette Archiv ist.

Schritt 4 – Die vier Dateien einsammeln:

/var/opt/gitlab/backups/<backup-id>_gitlab_backup.tar
/var/opt/gitlab/redis/dump.rdb
/etc/gitlab/gitlab.rb
/etc/gitlab/gitlab-secrets.json

Docker und Kubernetes

Läuft dein GitLab in Docker, lautet der Backup-Befehl docker exec -t <containername> gitlab-backup create; die vier Dateien liegen dann in den gemounteten Volumes (config/ für gitlab.rb und gitlab-secrets.json, data/backups/ bzw. data/redis/ für Archiv und Redis-Dump). Bei Kubernetes/Helm erzeugst du das Backup per kubectl exec mit dem backup-utility-Skript im Toolbox-Pod – siehe die Charts-Backup-Dokumentation. Bei einer selbst kompilierten Installation ist es sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production. Bist du unsicher, welcher Fall bei dir vorliegt: frag uns einfach vorher.

Vorher einmal proben

Du kannst sudo gitlab-backup create gefahrlos schon vor dem Wartungsfenster im laufenden Betrieb ausführen. Ein solches Backup ist nicht konsistent genug für den echten Umzug, aber du erfährst damit, wie lange der Lauf dauert und wie groß das Archiv wird – beides brauchen wir für die Planung.

Das Tar-Archiv ist typischerweise mehrere bis viele GB groß. Für die Übergabe stellen wir dir einen Upload-Bereich bereit (Nextcloud oder Seafile), alternativ per scp/rsync in ein von uns vorbereitetes Verzeichnis.

gitlab-secrets.json und gitlab.rb enthalten Secrets im Klartext. Übergib sie deshalb getrennt vom Archiv und verschlüsselt – etwa als Eintrag in einem geteilten Vaultwarden-Tresor, per Hemmelig oder GPG-verschlüsselt.

Deine Instanz bei server.camp konfigurieren wir plattformseitig – Reverse Proxy, Zertifikate, Ports, Backups, Monitoring und die Performance-Parameter leiten wir aus deinem Tarif ab. Eine eingelegte gitlab.rb würde beim nächsten Deployment überschrieben.

Wir lesen sie deshalb, gehen sie bei Bedarf mit dir durch und entscheiden je Einstellung:

Schick uns die gitlab.rb deshalb früh, nicht erst am Tag des Umzugs: Alles, was übernommen werden soll, ist eine Änderung an deiner Subscription – und die planen wir gemeinsam vor dem Wartungsfenster.

Diese Punkte gelten für beide Wege:

• Eigene Domain: Willst du deine bisherige Domain weiternutzen, richten wir mit dir ein – siehe Eigene Domain.
• Git-Remotes umstellen: Deine Repositories liegen ggf. unter einer neuen Domain. Die korrekte Klon-URL zeigt GitLab in jedem Projekt unter Code → Klonen an. Deine Entwickler passen ihre Remotes mit git remote set-url origin <neue-url> an.
• Git über SSH: Wir veröffentlichen Git-over-SSH auf einem eigenen Port pro Instanz, nicht auf Port 22. Den Port enthält die von GitLab angezeigte SSH-Klon-URL (ssh://git@…:<port>/…); alternativ hinterlegt man ihn einmal in ~/.ssh/config. Klonen über HTTPS ist davon nicht betroffen.
• SSH-Host-Keys (nur Weg B): Auf Wunsch übernehmen wir die Host-Keys deiner alten Instanz. Dann sehen deine Entwickler beim ersten Push keine Warnung „REMOTE HOST IDENTIFICATION HAS CHANGED". Sag uns einfach vorher, ob wir das machen sollen.
• Runner prüfen: Bei Weg A müssen Runner immer neu registriert werden, bei Weg B in der Regel nicht. Prüfe nach dem Umzug unter Einstellungen → CI/CD → Runner, ob deine Runner online sind.
• Hardware-Schlüssel und Passkeys neu registrieren (nur Weg B): WebAuthn-Registrierungen sind kryptografisch an die alte Domain gebunden. Läuft deine Instanz nach dem Umzug unter einer neuen Domain, werden die hinterlegten Geräte deaktiviert und müssen einmal neu registriert werden. Zeitbasierte Einmalcodes (TOTP-Apps) sind davon nicht betroffen – sie funktionieren weiter, sofern gitlab-secrets.json mitgekommen ist.
• Registry-Referenzen: Mit der neuen Registry-Domain ändern sich Docker-Logins sowie die image:-Angaben in .gitlab-ci.yml und in deinen Deployment-Manifesten.
• Backups und Monitoring laufen ab dem ersten Deployment automatisch. Du musst nichts einrichten.
• Alte Instanz: Lass sie abgeschaltet – aber noch nicht gelöscht –, bis du die Migration abgenommen hast und ein paar Tage produktiv auf der neuen Instanz gearbeitet wurde.

Schreib uns über das Kundenportal, wenn du umziehen möchtest. Hilfreich für die erste Antwort sind diese Angaben:

• Liegt dein GitLab auf gitlab.com oder ist es selbst gehostet?
• Welche GitLab-Version läuft bei dir (/help in deiner Instanz)?
• Läuft bei dir Community Edition oder Enterprise Edition? (Steht ebenfalls unter /help.)
• Wie groß ist dein Datenbestand ungefähr (Anzahl Projekte, Größe des Backups)?
• Gibt es einen Wunschtermin für das Wartungsfenster?

Beim Direct Transfer von gitlab.com kannst du ohne Rückfrage direkt starten – melde dich einfach, wenn etwas nicht wie erwartet läuft.