Planen der Migration zu GitHub

Informationen zu Migrationen

Beim Wechsel zwischen GitHub-Produkten, z. B. von GitHub Enterprise Server zu GitHub Enterprise Cloud oder von einer anderen Codehosting-Plattform wie Bitbucket Server oder GitLab zu GitHub kann die Arbeit mitgenommen werden: Code, Codeverlauf und alle ehemaligen Unterhaltungen und die Zusammenarbeit.

Dieser Leitfaden führt dich durch die Planung und Ausführung einer erfolgreichen Migration. Du erfährst, wie du dich auf eine Migration vorbereitest, welche Tools zum Verschieben deiner Daten verfügbar sind und wie du diesen Vorgang erfolgreich gestaltest.

Migrationsterminologie

Bevor du jedoch mit dieser Anleitung deine Migration planst, lerne folgende wichtige Begriffe kennen.

Begriff	Definition
Codehostingplattform	Das Onlinetool, das du zum Hosten deiner Quellcodrepositorys und zur Zusammenarbeit verwendest, z. B. GitHub Enterprise Cloud, GitHub Enterprise Server, Bitbucket Server und GitLab.com.
Versionskontrollsystem (VCS)	Das Tool, mit dem du Änderungen am Quellcode auf dem Computer nachverfolgst und verwaltest, auf dem du diese Änderungen vornimmst. Wenn du beispielsweise GitHub oder GitLab als Codehostingplattform verwendest, verwendest du das Git-Versionskontrollsystem. Wenn du Azure DevOps als Codehostingplattform verwendest, kannst du entweder Git oder Team Foundation-Versionskontrolle (TFVC) als zugrunde liegendes Versionskontrollsystem verwenden. Es ist auch möglich, dass du überhaupt kein VCS verwendest.
Migrationsursprung	Der Ort, von dem aus du migrierst. In der Regel handelt es sich dabei um eine Codehostingplattform, aber es kann auch dein eigener Rechner oder ein freigegebenes Netzlaufwerk sein.
Migrationsziel	Das GitHub-Produkt, zu dem du migrierst.
Migrationspfad	Die Kombination aus Migrationsursprung und Migrationsziel, z. B. „Bitbucket Server zu GitHub Enterprise Cloud“. Für bestimmte Migrationspfade bietet GitHub spezielle Tools wie GitHub Enterprise Importer, die dir bei der Migration helfen.

Definieren des Migrationsumfangs

Bevor du deine Migration planen kannst, musst du festlegen, was du zu welchem Zeitpunkt migrieren willst.

Definieren von Ursprung und Ziel

Zuerst legst du fest, von wo aus die Daten migriert werden sollen. Dies ist in der Regel, aber nicht immer, eine Codehostingplattform.

Bei deiner Codehostingplattform kann es sich um ein GitHub -Produkt handeln, wie z. B. GitHub.com oder GitHub Enterprise Server, oder es kann eine andere Codehostingplattform sein, wie z. B. Bitbucket Server, GitLab oder Azure DevOps. Je nach Größe und Komplexität deines Unternehmens verwendest du möglicherweise mehrere verschiedene Codehostingplattformen.

Wenn du überhaupt keine Codehostingplattform verwendest, speicherst du deinen Code möglicherweise auf einem freigegebenen Netzlaufwerk.

Unabhängig davon, wo sich der Code befindet, ist dies der „Migrationsursprung“.

Zudem musst du wissen, zu welchem GitHub-Produkt du migrierst, d. h. zu welchem „Migrationsziel“. Hierbei kann es sich um GitHub.com, GHE.com oder GitHub Enterprise Server handeln.

Erstellen einer grundlegenden Bestandsliste der zu migrierenden Repositorys

Nachdem du den Ursprung und das Ziel der Migration identifiziert hast, legst du fest, welche Daten du migrieren musst.

Erstelle dazu eine Migrationsbestandsliste aller Repositorys in deinen Migrationsursprüngen, die migriert werden sollen. Es wird empfohlen, eine Tabelle anzulegen. Zunächst solltest du für jedes Repository die folgenden Daten eintragen:

• Name
• Besitzer: In GitHub wäre dies ein Organisation, aber in anderen Tools könnte es eine andere Art von Besitzer geben.
• URL
• Zeitstempel der letzten Aktualisierung
• Anzahl der Pull Requests (oder äquivalent in deinem Migrationsursprung)
• Anzahl der Issues (oder äquivalent in deinem Migrationsursprung)

Wenn du von GitHub Enterprise Cloud oder GitHub Enterprise Server migrieren möchtest, kannst du diese Daten mit der Erweiterung gh-repo-stats für GitHub CLI abrufen. gh-repo-stats stellt mit nur wenigen Befehlen eine Verbindung mit der API deines Migrationsursprungs her und erstellt eine CSV-Datei mit allen empfohlenen Feldern. Weitere Informationen findest du im Repository mona-actions/gh-repo-stats.

Wenn Sie von Azure DevOps migrieren, empfehlen wir den inventory-report Befehl in den ADO2GH extension of the GitHub CLI. Der inventory-report Befehl stellt eine Verbindung mit der Azure DevOps-API her und erstellt eine sehr einfache CSV-Datei mit einigen der oben vorgeschlagenen Felder. Weitere Informationen zum Installieren der ADO2GH extension of the GitHub CLI findest du unter Migrieren von Repositorys von Azure DevOps zu GitHub Enterprise Cloud.

Wenn Sie von Bitbucket Server oder Bitbucket Data Center migrieren, empfehlen wir den inventory-report Befehl im BBS2GH extension of the GitHub CLI. Der inventory-report Befehl verwendet die API Ihrer Bitbucket-Instanz, um eine einfache CSV-Datei zu erstellen. Weitere Informationen zum Installieren der BBS2GH extension of the GitHub CLI findest du unter Migrieren von Repositorys von Bitbucket Server zu GitHub Enterprise Cloud.

Für andere Migrationsursprünge erstellst du deine Migrationsbestandsliste selbst. Du kannst die Tabelle mit den Berichtstools des Ursprungs erstellen, falls verfügbar, oder mit der API, oder du erstellst die Bestandsliste manuell.

Notiere dir unabhängig davon, welchen Ansatz du für deine Migrationsbestandsliste wählst, die von dir gewählte Vorgehensweise oder die Befehle, die du ausgeführt hast. Es ist sehr wahrscheinlich, dass du deine Bestandsliste während der Migrationsplanung noch einmal überarbeiten möchtest.

Nachdem du über eine Liste aller Repositorys verfügst, kannst du entscheiden, welche du migrieren möchtest. Eine Möglichkeit besteht darin, einfach alles zu migrieren. Doch ist eine Migration auch eine gute Gelegenheit, die Repositorys zu bewerten und alle nicht mehr benötigten zu entfernen. Oft haben Unternehmen Hunderte oder sogar Tausende von ungenutzten und nicht benötigten Repositorys, deren Archivierung die Migration erheblich vereinfachen kann.

Messen der Größe deiner Repositorys

Nachdem du deine grundlegende Migrationsbestandsliste erstellt hast, sammelst du Informationen über die Größe deiner Repositorys. Wenn deine Repositorys groß sind oder einzelne Dateien über 100 MB enthalten, kann dies die Dauer und Risiken deiner Migration erhöhen und die dir zur Verfügung stehenden Migrationstools einschränken.

Wenn du Git als Versionskontrollsystem verwendest, sind nicht nur große Dateien, die sich derzeit im Repository befinden, von Bedeutung. Große Dateien im Verlauf deines Repositorys sind ebenfalls wichtig. Wenn du beispielsweise in der Vergangenheit eine Datei mit einer Größe von mehr als 100 MB in deinem Repository hattest, ist diese Datei weiterhin im Git-Verlauf vorhanden. Es sei denn, du hast den Verlauf umgeschrieben, um alle Spuren der Datei zu entfernen. Weitere Informationen zum Umschreiben des Verlaufs findest du unter Informationen zu großen Dateien auf GitHub.

Wenn du deine Bestandsliste mit gh-repo-stats erstellt hast, verfügst du bereits über einige grundlegende Informationen über die Größe deiner Repositorys. Um eine vollständige Bestandsliste für die Migration zu erstellen, musst du ausführlichere Details zu den Daten in deinen Repositorys abrufen.

Befolge als Nächstes die folgenden Anweisungen, um die genannten Daten deiner Migrationsbestandsliste für jedes Repository hinzuzufügen:

• Die Größe der größten Datei (auch als „Blob“ bezeichnet)
• Die Gesamtgröße aller Dateien („Blobs“)

Wenn du ein anderes Versionskontrollsystem als Git verwendest oder deine Dateien überhaupt nicht mit einem Versionskontrollsystem nachverfolgt werden, verschiebe zuerst die Repositorys nach Git. Weitere Informationen finden Sie unter Hinzufügen von lokal gehostetem Code zu GitHub.

Verwende dann das Open-Source-Tool git-sizer, um diese Daten für dein Repository abzurufen.

Voraussetzungen

1. Installieren von git-sizer. Weitere Informationen findest du im Repository github/git-sizer.
2. Um zu überprüfen, ob git-sizer installiert ist, führst du git-sizer –version aus. Wenn eine Ausgabe wie git-sizer release 1.5.0 angezeigt wird, war die Installation erfolgreich.
3. Installieren von jq. Weitere Informationen findest du in der jq-Dokumentation unter Herunterladen von jq.
4. Um zu überprüfen, ob jq installiert ist, führst du jq –-version aus. Wenn eine Ausgabe wie jq-1.6 angezeigt wird, war die Installation erfolgreich.

Messen der Repositorygröße mit git-sizer

1. Führe git clone --mirror aus, um das Repository aus dem Migrationsursprung zu klonen.
2. Navigiere zu dem Verzeichnis, in dem du dein Repository geklont hast.
3. Um die Größe der größten Datei in deinem Repository in Bytes abzurufen, führe git-sizer --no-progress -j | jq ".max_blob_size" aus.
4. Führe git-sizer --no-progress -j | jq ".unique_blob_size" aus, um die Gesamtgröße aller Dateien in deinem Repository in Bytes abzurufen.
5. Füge deinem Bestand die Werte aus den vorherigen Schritten hinzu.

Informationen zu Migrationstypen

Es gibt drei Ansätze für die Migration, die unterschiedliche Stufen der Migrationsgenauigkeit bieten.

Migrationstyp	Definition	Requirements (Anforderungen)
Momentaufnahme der Quelle	Migriere den aktuellen Status deines Codes, wie er heute ist, ohne den Revisionsverlauf einzubeziehen.	Möglich für jeden Ursprung und jedes Ziel, auch wenn der Code derzeit nicht in einem Versionskontrollsystem (Version Control System, VCS) nachverfolgt wird.
Quelle und Verlauf	Migriere den aktuellen Status deines Codes und dessen Revisionsverlauf.	Möglich, wenn du deine Änderungen in Git nachverfolgt oder ein Versionskontrollsystem hast, das vor der Migration in Git konvertiert werden kann.
Quelle, Verlauf und Metadaten	Migriere den aktuellen Status deines Codes und dessen Revisionsverlauf sowie den Verlauf zur Zusammenarbeit, z. B. Probleme, Pull Requests und Einstellungen.	Erfordert spezielle Tools, die nicht für alle Migrationspfade verfügbar sind.

Bei der Entscheidung, welcher Typ von Migration durchgeführt werden soll, musst du die Anforderungen deiner Organisation und die zur Verfügung stehenden Tools berücksichtigen.

Du kannst verschiedene Strategien für verschiedene Repositorys verwenden. So kann es sein, dass es einige alte, archivierte Repositorys gibt, bei denen der Verlauf nicht wichtig ist, während eine detailgetreue Migration für deinen aktivsten Code entscheidend ist.

Informationen zu unseren verschiedenen Migrationsunterstützungsmodellen

Du kannst eine „Self-Service-Migration“ durchführen, bei der du deine eigene Migration nur mithilfe unserer Dokumentation planst und ausführst, ohne dass sie von GitHub unterstützt wird.

Vielleicht möchtest du aber auch mit dem Expert Services-Team von GitHub oder einem GitHub-Partner zusammenarbeiten, was wir dann als „expertengeleitete Migration“ bezeichnen. Mit einer expertengeleiteten Migration profitierst du von dem Wissen und der Erfahrung eines Expertenteams, das zuvor Dutzende oder sogar Hunderte von Migrationen durchgeführt hat. Zudem erhältst du Zugriff auf zusätzliche Migrationstools, die bei Self-Service-Migrationen nicht verfügbar sind.

Wenn du große Datenmengen migrierst, profitierst du wohl von einer expertengeleiteten Migration. Wenn du beispielsweise Tausende von Repositorys oder komplexe Repositorys, die größer als 5 GB sind, solltest du dich mit Expert Services in Verbindung setzen.

Wenn du mehr über expertengeleitete Migrationen erfahren möchtest, wende dich an deine Kundenbetreuung oder Expert Services.

Auswahl der eingesetzten Tools

Berücksichtigen Sie das Ziel und die Quelle bei der Planung ihrer Migration. Diese Überlegungen bestimmen den Pfad für Ihre Migration. Weitere Informationen findest du unter Migrationspfade zu GitHub.

Entwerfen der Organisationsstruktur für das Migrationsziel

In GitHub gehört jedes Repository zu einer Organisation. Bei Organisationen handelt es sich um freigegebene Konten mit komplexen Sicherheits- und Verwaltungsfeatures, in denen Unternehmen und Open-Source-Projekte an vielen Projekten gleichzeitig zusammenarbeiten können. Weitere Informationen findest du unter Informationen zu Organisationen.

Unabhängig davon, ob du GitHub zum ersten Mal nutzt oder GitHub bereits verwendest, solltest du nach der Migration überlegen, welche die effektivste Struktur für deine Organisationen und Repositorys sind. Der von dir gewählte Entwurf kann die Zusammenarbeit und Ermittlung optimieren und den Verwaltungsaufwand minimieren oder unnötige Silos und verwaltungstechnischen Aufwand verursachen.

Es wird empfohlen, die Anzahl der Organisationen möglichst gering zu halten und sie nach einem von fünf Archetypen zu strukturieren. Ausführliche Anweisungen findest du unter Bewährte Methoden für die Strukturierung von Organisationen in deinem Unternehmen.

Durchführen einer Probelaufmigration für jedes Repository

Bevor du mit der Planung fortfährst, führe eine Probelaufmigration mit allen Repositorys durch. Umfassende Probeläufe ermöglichen Folgendes:

• Sicherstellen, dass das ausgewählte Tool für deine Repositorys geeignet ist
• Prüfen, ob das Tool deine Anforderungen erfüllt
• Genaues Festlegen, welche Daten migriert werden und welche nicht migriert werden
• Ermitteln, wie lange die Migration dauern wird, zur besseren Planung deiner Produktionsmigration

Eine Probelaufmigration ist nichts Besonderes. Führe einfach eine normale Migration aus, und lösche dann das Repository im Migrationsziel.

Plane deine Schritte vor und nach der Migration

Die Migration deiner Repositorys ist nur ein Schritt in einem größeren Migrationsprozess. Es gibt weitere Schritte, die du vornehmen musst, und möglicherweise musst du auch Daten oder Einstellungen manuell migrieren.

Die vollständige Liste der Schritte, die für deine Migration erforderlich sind, hängt von deinen individuellen Voraussetzungen ab. Es gibt jedoch einige Schritte vor der Migration, die für alle gelten:

• Informiere die Benutzer*innen im Voraus über die bevorstehende Migration und deren Zeitrahmen.
• Sende kurz vor der Migration eine Erinnerung.
• Richte für dein Team Benutzerkonten in GitHub ein.
• Sende Anweisungen an die Benutzer*innen, wie sie ihre lokalen Repositorys aktualisieren können, damit diese auf dein neues System zeigen.

Es gibt auch Schritte nach der Migration, die für alle Migrationen gelten:

• Informiere die Benutzer*innen darüber, dass die Migration abgeschlossen ist.
• Verknüpfe Aktivitäten mit Benutzer*innen in deinem Migrationsziel.
• Nimm deinen Migrationsursprung außer Betrieb.

Im Folgenden findest du einige weitere Schritte, die du bei der Planung deiner Migration berücksichtigen solltest.

Migrieren von Continuous Integration (CI) und Continuous Delivery (CD)

Wenn du zwischen GitHub-Produkten wechselst, GitHub Actions bereits für CI/CD verwendest und weiterhin GitHub Actions nutzt, gibt es nicht viel zu tun. Die Workflowdateien in deinen Repositorys werden automatisch für dich migriert. Wenn Du selbstgehostete Runner verwendest, musst du diese in deiner neuen GitHub-Organisation einrichten, damit diese deine Workflows ausführen können.

Wenn du GitHub Actions nicht verwendest, ist die Situation komplizierter. Wenn du weiterhin denselben CI/CD-Anbieter verwenden möchtest, musst du überprüfen, ob der Anbieter mit GitHub kompatibel ist, und den Anbieter mit deiner neuen Organisation und deinen neuen Repositorys verbinden.

Wenn du zu GitHub Actions wechseln möchtest, empfehlen wir dir, dies nicht gleichzeitig mit der Migration deiner Repositorys zu tun. Warte lieber bis zu einem späteren Zeitpunkt und führe deine CI/CD-Migration in einem separaten Schritt durch. So hast du den Migrationsprozess besser im Griff. Wenn du mit der Migration beginnen möchtest, gehe zu Zu GitHub-Aktionen migrieren.

Migrieren von Integrationen

Wahrscheinlich nutzt du mit deinem Codehostinganbieter Integrationen, die entweder intern entwickelt oder von anderen Anbietern bereitgestellt werden.

Wenn du GitHub bereits verwendest, musst du deine Integrationen neu konfigurieren, um auf deine neuen Organisationen und Repositorys zu verweisen. Wenn die Integration von einem Anbieter bereitgestellt wird, wende dich an den Anbieter, um Anweisungen zu erhalten. Wenn die Integration intern entwickelt wurde, konfiguriere die Integration in deiner neuen Organisation neu, und generiere neue Token und Schlüssel.

Wenn du noch nicht mit GitHub vertraut bist, prüfe, ob deine Integrationen mit GitHub kompatibel sind, und konfiguriere sie dann neu. Wenn du intern entwickelte Integrationen verwendest, schreibe diese neu, um mit der GitHub-API zu arbeiten. Weitere Informationen finden Sie unter Dokumentation zu GitHub-REST-API.

Verknüpfen von Aktivitäten mit Benutzer*innen in deinem Migrationsziel

Wenn du den Verlauf über die Zusammenarbeit oder Metadaten sowie Code migrierst, musst du die Aktivitäten der Benutzer*innen mit ihren neuen Identitäten in deinem Migrationsziel verknüpfen.

Angenommen @octocat hat ein Issue für deine GitHub Enterprise Server-Instanz erstellt, und du wechselst zu GitHub Enterprise Cloud. In GitHub Enterprise Cloud hat @octocat möglicherweise einen völlig anderen Benutzernamen. Der Zuordnungsprozess ermöglicht es, Benutzeraktivitäten mit diesen neuen Identitäten zu verknüpfen.

Die Art und Weise, wie die Zuordnung funktioniert, ist je nach Tool unterschiedlich:

• Wenn du ghe-migrator, gl-exporter oder bbs-exporter verwendest, entscheidest du im Voraus, wie du Daten zuordnen möchtest, und schließt beim Importieren deiner Daten eine Zuordnungsdatei ein.
• Wenn du GitHub Enterprise Importer verwendest, werden Daten mit Platzhalteridentitäten verknüpft, die als „Mannequins“ bezeichnet werden. Du kannst diesen Verlauf zudem echten Benutzer*innen zuweisen, nachdem deine Daten migriert wurden. Weitere Informationen finden Sie unter Freigeben von Mannequins für GitHub Enterprise Importer.

Verwalten von Teams und Berechtigungen

Die meisten Kunden verwenden Teams, um den Zugriff auf Repositorys zu verwalten. Anstatt Mona direkt Zugriff auf ein Repository zu geben, kannst du Mona mit Teams dem Engineering-Team hinzufügen und allen Mitgliedern des Engineering-Teams Zugriff auf das Repository gewähren. Weitere Informationen finden Sie unter Informationen zu Teams.

Du kannst deine Teams erstellen und Teammitglieder hinzufügen, bevor du deine Repositorys migrierst. Möglicherweise möchtest du deine Mitglieder über deinen Identitätsanbieter (Identity Provider, IdP) verwalten, indem du deine Teams mit IdP-Gruppen verknüpfst. Weitere Informationen finden Sie unter Ein Team mit einer Identitätsanbieter-Gruppe synchronisieren.

Du kannst deine Teams jedoch erst an Repositorys anfügen, nachdem du die Repositorys migriert hast.