> ## Documentation Index
> Fetch the complete documentation index at: https://docs.netzfabrik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration zu Managed GitLab

> Schritt-für-Schritt-Anleitung für die Migration von gitlab.com, einer selbst gehosteten GitLab-Instanz oder GitHub zu deinem Managed GitLab.

Du möchtest von einer bestehenden GitLab-Instanz, von gitlab.com oder von GitHub zu deinem Managed GitLab bei NETZFABRIK wechseln? Wir unterstützen dich bei der Migration.

***

## Migrationswege

| Quelle                       | Methode                                                          |
| ---------------------------- | ---------------------------------------------------------------- |
| **Selbst gehostetes GitLab** | Vollständiges Backup/Restore oder Projekt-Export/Import          |
| **gitlab.com**               | Projekt-Export/Import (Projekte einzeln oder per API)            |
| **GitHub**                   | GitLab-Importer für Repositories, Issues, Pull Requests und Wiki |
| **Bitbucket**                | GitLab-Importer für Repositories und Pull Requests               |
| **Andere Git-Hosts**         | Git-Repository per Remote-URL importieren (nur Code-History)     |

***

## Vorbereitung

Bevor die Migration startet, empfehlen wir folgende Schritte:

1. **Bestandsaufnahme** – Verschaffe dir einen Überblick über Repository-Größen, Benutzeranzahl, angebundene Dienste und CI/CD-Workflows.
2. **Datenbereinigung** – Nutze die Gelegenheit, veraltete Projekte, ungenutzte Branches oder historische Artefakte aufzuräumen. Das vereinfacht die Migration und verbessert die Performance danach.
3. **Backup erstellen** – Stelle sicher, dass ein aktuelles, vollständiges Backup deiner Quellinstanz existiert und zugänglich ist.
4. **Stakeholder informieren** – Informiere dein Team über geplante Downtimes, Änderungen an Workflows und den Zeitplan.

***

## Migration von einer bestehenden GitLab-Instanz

Bei der Migration von einer selbst gehosteten GitLab-Instanz gibt es zwei Ansätze:

**Vollständiges Backup/Restore (empfohlen)**

Die umfassendste Methode. Alle Daten werden übernommen: Repositories, Issues, Merge Requests, CI/CD-Konfiguration, Container Registry, Benutzer und Berechtigungen.

Voraussetzung: Die Quell- und Zielinstanz sollten auf der gleichen GitLab-Major-Version laufen. Wir stimmen die Versionen vorab mit dir ab.

Für die Migration benötigen wir von dir:

* **Vollständiges Backup** – Der GitLab-Backup-Dump (`*_gitlab_backup.tar`)
* **Secrets** – `gitlab-secrets.json` (enthält Verschlüsselungskeys für CI/CD-Variablen, 2FA etc.)
* **Konfiguration** – `gitlab.rb` (bei Omnibus-Installationen) mit deinen Anpassungen
* **Gewünschte Hostnamen** – Für GitLab und die Container Registry

In der Regel schließen wir die Migration **innerhalb weniger Stunden** ab.

**Projekt-Export/Import**

Einzelne Projekte werden als Archiv exportiert und auf der neuen Instanz importiert. Geeignet, wenn nur bestimmte Projekte migriert werden sollen.

***

## Migration von gitlab.com oder GitHub

Diese Migrationen nimmst du selbst über die GitLab-Oberfläche vor:

1. Melde dich an deiner Managed-GitLab-Instanz an
2. Erstelle ein neues Projekt und wähle **Import project**
3. Wähle die Quelle (gitlab.com, GitHub, Bitbucket, etc.)
4. Authentifiziere dich bei der Quelle und wähle die zu importierenden Projekte

Der Import übernimmt je nach Quelle: Repositories, Issues, Merge/Pull Requests, Labels, Milestones und Wiki.

***

## Was wir für dich übernehmen

* **Versionsabgleich** – Wir stellen sicher, dass deine Managed-Instanz auf der richtigen Version läuft
* **Backup/Restore** – Bei vollständigen Migrationen spielen wir das Backup auf der neuen Instanz ein
* **DNS-Umstellung** – Wir unterstützen bei der Umstellung der Domain auf die neue Instanz
* **Testlauf** – Auf Wunsch migrieren wir zuerst in eine Testumgebung, bevor wir live gehen
* **Nachkontrolle** – Wir prüfen nach der Migration, ob alle Daten korrekt übernommen wurden

***

## Häufige Fehler bei Migrationen

* **Hoher Versionsunterschied** – Quell- und Zielinstanz müssen auf der gleichen Major-Version laufen. Ein Backup von GitLab 16.x kann nicht direkt auf GitLab 17.x eingespielt werden. Bei großen Versionssprüngen sind Zwischenupdates auf der Quellinstanz nötig, bevor die Migration möglich ist.
* **Unvollständige Background-Migrations** – GitLab führt bei Updates Datenbank-Migrationen im Hintergrund durch. Wurden diese auf der Quellinstanz nicht vollständig abgeschlossen, kann es nach der Migration zu Inkonsistenzen kommen. Wir prüfen das vorab.
* **Sehr große Backups** – Bei sehr großen Instanzen (viele Repositories, große LFS-Objekte, umfangreiche Container Registry) kann die Migration länger dauern. In solchen Fällen planen wir eine inkrementelle Migration, um die Downtime zu minimieren.
* **Fehlende LFS-Objekte** – Git LFS-Dateien werden beim Projekt-Export nicht immer mitgenommen. Wir prüfen das gesondert.
* **CI/CD-Variablen** – Projekt- und Gruppen-Variablen werden beim Export nicht exportiert. Diese müssen manuell übertragen werden.
* **Inkompatible Konfigurationen** – Custom Hooks, Plugins oder spezielle Serverkonfigurationen sind auf der neuen Instanz möglicherweise nicht 1:1 kompatibel. Wir prüfen die Konfiguration vorab und passen sie an.

***

## Migration starten

Kontaktiere uns mit folgenden Informationen:

* **Quelle** – Von wo wird migriert? (Self-hosted GitLab, gitlab.com, GitHub, etc.)
* **Umfang** – Alle Projekte oder nur bestimmte?
* **GitLab-Version** – Bei Self-hosted: aktuelle Version der Quellinstanz
* **Zeitrahmen** – Bis wann soll die Migration abgeschlossen sein?

Wir planen die Migration gemeinsam mit dir und sorgen für einen reibungslosen Übergang.