Weiterführende Migrationshinweise

Auf dieser Seite finden Sie zusätliche Hinweise und Erläuterungen rund um die Migration von einem externen GitLab zu git.nrw. Wir werden die Seite stetig erweitern.

1. Die Migrationsarten

Für den Transfer von Daten stehen primär zwei Methoden zur Verfügung: Direct-Transfer und der klassische dateibasierte Export/Import einzelner Repositories.

Wichtiger Hinweis zu privaten Projekten: Da der Direct-Transfer auf Gruppenebene operiert, können rein private Projekte auf diesem Weg nicht direkt migriert werden. Verschieben Sie private Projekte vor Beginn der Migration auf der Quellplattform temporär in eine Gruppe, um auch für diese Direct-Transfer nutzen zu können.

2. Transfer-Umfang

Direct-Transfer migriert den Großteil eines Repositorys. Ausnahmen bilden hierbei Artefakte und Packages sowie die Container-Registry. Dabei werden Artefakte und Packages bei dem ersten Durchlauf der CI-Pipeline auf git.nrw neu generiert. Die Container Registry muss allerdings neu eingerichtet werden.

Eine vollständige Auflistung der im direct-transfer migrierten und ausgeschlossenen Daten finden sie in der GitLab Dokumentation .

3. Vorbereitung der Migration

Folgende Schritte helfen bei einer reibungslosen Migration und sollten ohnehin ab und zu in Ihren Repositories ausgeführt werden.

3.1. Bereinigung des Repositories

• Dateigrößen prüfen: Überprüfen Sie das Repository auf große, nicht zwingend erforderliche Dateien (z. B. Binärdaten, Logfiles, temporäre Build-Ergebnisse).
• Bereinigungswerkzeuge: Es gibt Tools, um das Finden und Bereinigen von großen Dateien zu erleichtern. GitLab empfiehlt hier git-filter-repo .
• Housekeeping: Nach dem Löschen von Objekten bleiben diese zunächst in den alten Commits. Starten Sie das Housekeeping in den GitLab-Projekteinstellungen manuell, um den Speicherplatz auf dem Server durch Garbage Collection freizugeben. Beachten Sie, das Garbage Collection von GitLab zeitlich geplant wird, das Aufräumen findet also zeitversetzt statt.

4. Gruppen

In git.nrw müssen Top-Level-Gruppen bei Ihrer Heimateinrichtung beantragt werden. Es ist daher ggf. notwendig sich vor einer Migration über die Gruppenstruktur in git.nrw noch einmal gesondert Gedanken zu machen.

Der Direct-Transfer migriert von der Quellinstanz ganze Gruppenstrukturen von der Top-Level-Gruppe ausgehend. Das hat zur Folge, dass diese Gruppenstruktur als Subgruppe der zuvor erstellten Top-Level-Gruppe in git.nrw migriert wird. Es entsteht eine zusätzliche Hierachie-Ebene, was Auswirkung auf die Projektpfade hat.

Siehe auch dazu unsere Hinweise zu Gruppen .

5. User-Management

GitLab kann keine User von einem GitLab auf das andere übertragen. Während des Transfers werden aber sogenannte Placeholder (Platzhalter) User in die migrierte Top-Level-Gruppe übertragen. Diesen hängen sämtliche Tätigkeiten (bspw.: commits) des ursprünglichen Users aus dem Quell-GitLab an. Durch Zuweisung der Placeholder zu realen Usern auf git.nrw , werden also die vorherigen Beziehungen widerhergestellt. Wird es den User auf git.nrw nicht mehr geben (bspw.: Hochschule bereits verlassen), so bleiben bspw. den commits die commit-Mail-Adressen erhalten um eine Zuordnung sicherzustellen.

Wichtig: GitLab intern hat jeder User eine interne User-ID anhand derer Verknüpfungen passieren. Eine Änderung des Usernames oder Klarnamen spielt für die Zuordnung zu den Daten in GitLab also keine Rolle.

6. Umgang mit dem 2GB-repo-size-limit und Oversized-Projekten

Auf der Zielplattform git.nrw gilt ein Speicherplatz-Limit (Quota) von 2 GB pro Projekt (schließt LFS explizit mit ein), wobei folgende Daten nicht in die Quota mit einbezogen werden:

• Artifacts
• Containers
• Packages
• Snippets
• Uploads
• Wikis

Quelle: https://docs.gitlab.com/administration/settings/account_and_limit_settings/#repository-size-limit

Hinweis: Wie genau sich das repo-size-limit in Ihrem Projekt zusammensetzt, finden Sie auf der Startseite jedes Projektes auf der rechten Seite unter:

Bei Überschreitung der repo-size-limit passiert folgendes:

• Projekte innerhalb von Gruppen: Im direct-transfer werden die Projekte trotz Überschreitung des repo-size-limits übertragen. Das Projekt wird auf git.nrw als read-only markiert. Ein Push oder eine Pipeline-Ausführung ist erst wieder möglich, wenn das repo-size-limit wieder eingehalten wird.

• Private Projekte: Überschreitet ein Import in den persönlichen Namespace (oder eines einzelnen Projektes in einer Gruppe) das Limit, schlägt der Importprozess fehl und bricht ab. Hier ist eine vorherige Bereinigung, oder für den reinen Transfer, ein Verschieben des Projektes in eine zu migriende Gruppe, nötig.

  Tipp: Wenn Sie mit großen externen Daten arbeiten müssen, werfen Sie einmal einen Blick auf git-annex . Hierbei ist es möglich mit externen Datenspeichern zu interagieren. Wir bitten allerdings um Verständnis, dass wir zu git-annex keinen Support anbieten können.

7. Nach der Migration

Eine Liste von Empfehlungen nach der Migration:

• Überprüfen Sie die Funktionalität Ihrer Prozesse und passen diese ggf. an

  • Registrieren Sie ggf. genutzte GitLab-Runner neu
  • Richten Sie ggf. die Container-Registry neu ein
  • Passen Sie Pfade und Secrets an
  • etc.

• Aktualisieren Sie ihre lokalen Git repositories: Update git remote URLs

• Falls Ihre Projekte Submodule mit absoluten URLs zur alten Instanz enthalten, können Sie diese über eine globale Git-Konfiguration transparent umleiten, ohne .gitmodules in jedem Repo anpassen zu müssen:

  git config --global --add "url.https://gitlab.git.nrw/<group>/.insteadOf" "https://example-gitlab.com/<group>/"

• Stellen Sie sicher, dass die neue URL interessierten Parteien bekannt gemacht wird

  • Schließen Sie eine weitere Bearbeitung des Projektes durch andere Personen auf der Quellinstanz aus (z.B.: Durch Löschung oder Archivierung)