Migrieren von Repositorys von Bitbucket Server zu GitHub Enterprise Cloud

Informationen zu Repositorymigrationsvorgängen mit GitHub Enterprise Importer

Du kannst einzelne Repositorys oder alle Repositorys mithilfe der GitHub CLI aus einer BitBucket Server-Instanz migrieren.

Die Migration von Bitbucket Server mithilfe der GitHub-API wird derzeit nicht unterstützt.

Voraussetzungen

• To ensure you understand the known support limitations of the Importer, review "About GitHub Enterprise Importer."
• We strongly recommend that you perform a trial run of your migration and complete your production migration soon after. To learn more about trial run best practices, see "Vorbereiten einer Migration mit GitHub Enterprise Importer."
• Es ist zwar nicht erforderlich, die Arbeit während der Produktionsmigration zu unterbrechen, es wird aber empfohlen. Der Importer unterstützt keine Deltamigrationen, sodass Änderungen, die während der Migration vorgenommen werden, nicht migriert werden. Wenn du dich dafür entscheidest, die Arbeit während der Produktionsmigration nicht zu unterbrechen, musst du diese Änderungen manuell migrieren.
• Für die Zielorganisation auf GitHub.com musst du Organisationsbesitzer*in sein oder über die Migratorrolle verfügen. Weitere Informationen findest du unter Zuweisen der Migrationsrolle zu GitHub Enterprise Importer.
• Du benötigst den Benutzernamen und das Kennwort für ein Bitbucket Server-Konto mit Administrator- oder Superadministratorberechtigungen.

Schritt 1: Installieren der BBS2GH extension of the GitHub CLI

Wenn dies deine erste Migration ist, musst du die BBS2GH extension of the GitHub CLI installieren. Weitere Informationen zur GitHub CLI findest du unter Informationen zur GitHub CLI.

1. Installiere die GitHub CLI. Installationsanweisungen für GitHub CLI findest du im GitHub CLI-Repository.

   Hinweis: Du benötigst Version 2.4.0 oder höher der GitHub CLI. Die installierte Version kannst du mit dem Befehl gh --version ermitteln.

2. Installiere die BBS2GH extension.

   Shell

   gh extension install github/gh-bbs2gh

Any time you need help with the BBS2GH extension, you can use the --help flag with a command. For example, gh bbs2gh --help will list all the available commands, and gh bbs2gh migrate-repo --help will list all the options available for the migrate-repo command.

Schritt 2: Aktualisieren der BBS2GH extension of the GitHub CLI

Die BBS2GH extension of the GitHub CLI wird wöchentlich aktualisiert. To make sure you're using the latest version, update the extension.

gh extension upgrade github/gh-bbs2gh

Schritt 3: Festlegen der Umgebungsvariablen

Bevor du die BBS2GH extension für die Migration zu GitHub Enterprise Cloud verwenden kannst, musst du ein personal access token erstellen, das Zugriff auf die Zielorganisation hat, und dann das personal access token als Umgebungsvariable festlegen.

Außerdem müssen Umgebungsvariablen für den Benutzernamen und das Kennwort deiner Bitbucket Server-Instanz sowie ggf. für dein SMB-Kennwort festgelegt werden. Letzteres ist erforderlich, wenn deine Bitbucket Server-Instanz unter Windows ausgeführt wird.

1. Erstelle ein personal access token für die Authentifizierung der Zielorganisation auf GitHub Enterprise Cloud, und stelle sicher, dass das Token alle Anforderungen erfüllt. Weitere Informationen findest du unter Verwalten des Zugriffs für GitHub Enterprise Importer.

2. Lege Umgebungsvariablen fest, und ersetze dabei „TOKEN“ durch das weiter oben erfasste personal access token, „USERNAME“ durch den Benutzernamen eines Bitbucket Server-Kontos mit Administrator- oder Superadministratorberechtigungen, und „PASSWORD“ durch das Kennwort für das Bitbucket Server-Konto.

   • Wenn du ein Terminal verwendest, führe den Befehl export aus.

     Shell

     export GH_PAT="TOKEN"
     export BBS_USERNAME="USERNAME"
     export BBS_PASSWORD="PASSWORD"
     # If your Bitbucket Server instance runs on Windows
     export SMB_PASSWORD="PASSWORD"

   • Wenn du PowerShell verwendest, führe den Befehl $env aus.

     Shell

     $env:GH_PAT="TOKEN"
     $env:BBS_USERNAME="USERNAME"
     $env:BBS_PASSWORD="PASSWORD"
     # If your Bitbucket Server instance runs on Windows
     $env:SMB_PASSWORD="PASSWORD"

Schritt 4: Einrichten des Blobspeichers

Da sich viele Bitbucket Server-Instanzen hinter einer Firewall befinden, verwendet die GitHub CLI Blobspeicher als Zwischenspeicherort für Daten, die über das Internet erreichbar sind.

Du generierst zunächst ein Archiv der Daten, die du migrieren möchtest, und pushst die Daten durch deine Firewall in den Blobspeicher.

Die GitHub CLI unterstützt die folgenden Blobspeicheranbieter:

• Amazon Web Services S3 (AWS)
• Azure Blob Storage

Bevor du eine Migration ausführen kannst, musst du einen Speichercontainer mit dem gewünschten Cloudanbieter zum Speichern deiner Daten einrichten.

Einrichten eines AWS S3-Speicherbuckets

Richte in AWS einen S3-Bucket ein. Weitere Informationen findest du unter Erstellen von Buckets in der AWS-Dokumentation.

Außerdem benötigst du einen AWS-Zugriffsschlüssel und einen geheimen Schlüssel mit read-write-Zugriff auf deinen Bucket.

Wenn du bereit bist, die Migration auszuführen, musst du deine AWS-Anmeldeinformationen in der GitHub CLI angeben: Region, Zugriffsschlüssel, geheimer Schlüssel und Sitzungstoken (falls erforderlich). Du kannst sie als Argumente übergeben oder die Umgebungsvariablen AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY und AWS_SESSION_TOKEN festlegen.

Du musst auch den Namen des S3-Buckets im --aws-bucket-name.Argument übergeben.

Einrichten eines Azure Blob Storage-Speicherkontos

Erstelle in Azure ein Speicherkonto, und notiere dir die Verbindungszeichenfolge. Weitere Informationen findest du unter Verwalten von Speicherkonto-Zugriffsschlüsseln in der Microsoft-Dokumentation.

Wenn du bereit bist, die Migration auszuführen, kannst du deine Verbindungszeichenfolge entweder als Argument an die GitHub CLI übergeben oder mithilfe der Umgebungsvariable AZURE_STORAGE_CONNECTION_STRING übergeben.

Schritt 5: Migrieren eines Repositorys

Du kannst Repositorys mit dem Befehl gh bbs2gh migrate-repo migrieren.

Beim Migrieren von Repositorys führt die BBS2GH extension of the GitHub CLI standardmäßig die folgenden Schritte aus:

1. Herstellen einer Verbindung mit deiner Bitbucket Server-Instanz und Generieren jeweils eines Migrationsarchivs pro Repository
2. Herunterladen des Migrationsarchivs aus der Bitbucket Server-Instanz auf den Computer, auf dem die BBS2GH extension of the GitHub CLI ausgeführt wird – unter Verwendung von SFTP (Linux) oder SMB (Windows)
3. Hochladen der Migrationsarchive in den Blobspeicheranbieter deiner Wahl
4. Starten der Migration in GitHub Enterprise Cloud mithilfe der URLs der Archive, die bei deinem Blobspeicheranbieter gespeichert sind
5. Löschen des Migrationsarchivs

Alternativ dazu kannst du das Archiv über die GitHub CLI generieren, dieses Archiv manuell herunterladen und dann die Migration über die GitHub CLI fortsetzen.

• Zulassen, dass die GitHub CLI das Migrationsarchiv herunterlädt
• Manuelles Herunterladen des Migrationsarchivs

Zulassen, dass die GitHub CLI das Migrationsarchiv herunterlädt

Verwende den Befehl gh bbs2gh migrate-repo, um ein einzelnes Repository zu migrieren.

Dieser Schritt muss über einen Computer ausgeführt werden, der über Zugriff auf Folgendes verfügt:

• Deine Bitbucket Server-Instanz über HTTPS
• Deine Bitbucket Server-Instanz über SFTP, wenn deine Bitbucket Server-Instanz unter Linux ausgeführt wird. Allgemein gilt: Wenn du über SSH auf den Server zugreifen kannst, kannst du auch SFTP verwenden.
• Deine Bitbucket Server-Instanz über SMB, wenn deine Bitbucket Server-Instanz unter Windows ausgeführt wird
• Deinen ausgewählten Blobspeicheranbieter

gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT --bbs-repo CURRENT-NAME \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.

Platzhalter | Wert | ----------- | ----- | BBS-SERVER-URL | Die URL für deine Bitbucket Server-Instanz PROJECT | The key for the Bitbucket Server project of the repository you want to migrate CURRENT-NAME | Der Name des Repositorys, das du migrieren möchtest DESTINATION | Name of the destination organization NEW-NAME | Der Name für das migrierte Repository SSH-USER | Der Benutzername, der beim Herstellen einer Verbindung mit deinem Bitbucket-Server über SFTP verwendet werden soll, wenn deine Bitbucket Server-Instanz unter Linux ausgeführt wird PATH-TO-KEY | If your Bitbucket Server instance runs on Linux, the path to your SSH private key, such as ~/.ssh/id_rsa. For SSH key requirements, see "Verwalten des Zugriffs für GitHub Enterprise Importer". SMB-USER | Der Benutzername, der beim Herstellen einer Verbindung mit deinem Bitbucket-Server über SMB verwendet werden soll, wenn deine Bitbucket Server-Instanz unter Windows ausgeführt wird AWS-BUCKET-NAME | Der Bucketname für deinen AWS S3-Bucket

Manuelles Herunterladen des Migrationsarchivs

Standardmäßig führt die BBS2GH extension of the GitHub CLI die gesamte Migration aus und lädt auch das Migrationsarchiv über SFTP oder SMB von der Bitbucket Server-Instanz herunter.

Einige Kunden ziehen es jedoch vor, das Migrationsarchiv manuell herunterzuladen, beispielsweise weil ihr Server keinen SFTP-Zugriff bietet. In diesem Fall kannst du das Archiv über die GitHub CLI generieren, dieses Archiv manuell herunterladen und dann die Migration über die GitHub CLI fortsetzen.

Dieser Schritt muss über einen Computer ausgeführt werden, der über Zugriff auf Folgendes verfügt:

• Deine Bitbucket Server-Instanz über HTTPS
• Deinen ausgewählten Blobspeicheranbieter

Verwende den Befehl gh bbs2gh migrate-repo zunächst nur mit den folgenden Argumenten:

gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME

Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.

Platzhalter | Wert | ----------- | ----- | BBS-SERVER-URL | Die URL für deine Bitbucket Server-Instanz PROJECT | The key for the Bitbucket Server project of the repository you want to migrate CURRENT-NAME | Der Name des Repositorys, das du migrieren möchtest

Dein Migrationsarchiv wird generiert, und der Pfad wird in der Befehlsausgabe ausgegeben:

[12:14] [INFO] Export completed. Your migration archive should be ready on your
instance at $BITBUCKET_SHARED_HOME/data/migration/export/Bitbucket_export_9.tar

Im Allgemeinen wird $BITBUCKET_SHARED_HOME unter Linux auf /var/atlassian/application-data/bitbucket/shared und unter Windows auf C:\Atlassian\ApplicationData\Bitbucket\Shared festgelegt, die Werte können jedoch je nach Serverkonfiguration abweichen. Informationen zum Identifizieren deines freigegebenen Basisverzeichnisses findest du unter Behandeln von Problemen bei der Migration mit GitHub Enterprise Importer.

Lade das Migrationsarchiv von deiner Bitbucket Server-Instanz herunter und speichere es auf dem Computer, auf dem du die GitHub CLI ausführst.

Um das Migrationsarchiv in GitHub zu importieren, verwende den Befehl gh bbs2gh migrate-repo erneut, aber diesmal mit anderen Argumenten:

gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.

Platzhalter | Wert | ----------- | ----- | ARCHIVE-PATH | The path to the Bitbucket Server migration archive you downloaded from your instance DESTINATION | Name of the destination organization NEW-NAME | Der Name für das migrierte Repository AWS-BUCKET-NAME | Der Bucketname für deinen AWS S3-Bucket

Schritt 6: Überprüfen der Migration und des Fehlerprotokolls

Nachdem die Migration abgeschlossen ist, solltest du das Migrationsprotokoll überprüfen. Weitere Informationen findest du unter Zugreifen auf die Migrationsprotokolle für GitHub Enterprise Importer.

Es wird empfohlen, die Integrität deiner migrierten Repositorys zu überprüfen.

Schritt 7: Migrieren mehrerer Repositorys

If you want to migrate multiple repositories to GitHub Enterprise Cloud at once, use the GitHub CLI to generate a migration script. The resulting script will contain a list of migration commands, one per repository.

Generieren eines Migrationsskripts

Für diesen Schritt muss ein Computer verwendet werden, der über HTTPS auf deine Bitbucket Server-Instanz zugreifen kann.

Führe den Befehl gh bbs2gh generate-script aus, um ein Migrationsskript zu generieren.

gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
  --github-org DESTINATION \
  --output FILENAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER

If you want the script to download the migration log for each migrated repository, add the --download-migration-logs flag. For more information about migration logs, see "Zugreifen auf die Migrationsprotokolle für GitHub Enterprise Importer."

Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.

Platzhalter | Wert | ----------- | ----- | BBS-SERVER-URL | Die URL für deine Bitbucket Server-Instanz DESTINATION | Name of the destination organization FILENAME | Ein Dateiname für das resultierende Migrationsskript

Wenn du das Terminal verwendest, legst du als Erweiterung .ps1 fest, da für das generierte Skript PowerShell ausgeführt werden muss. Du kannst PowerShell für Mac oder Linux installieren. SSH-USER | Der Benutzername, der beim Herstellen einer Verbindung mit deinem Bitbucket-Server über SFTP verwendet werden soll, wenn deine Bitbucket Server-Instanz unter Linux ausgeführt wird PATH-TO-KEY | If your Bitbucket Server instance runs on Linux, the path to your SSH private key, such as ~/.ssh/id_rsa. For SSH key requirements, see "Verwalten des Zugriffs für GitHub Enterprise Importer". SMB-USER | Der Benutzername, der beim Herstellen einer Verbindung mit deinem Bitbucket-Server über SMB verwendet werden soll, wenn deine Bitbucket Server-Instanz unter Windows ausgeführt wird

Überprüfen des Migrationsskripts

Nachdem du das Skript generiert hast, überprüfst du die Datei, und bearbeitest ggf. das Skript.

• Wenn du einige Repositorys nicht migrieren möchtest, kannst du die entsprechenden Zeilen löschen oder auskommentieren.
• Standardmäßig wird für Repositorynamen in GitHub eine Konvention vom Typ projectKey-repositoryName verwendet. So wird beispielsweise ein Bitbucket Server-Repository namens airports, das zum Projekt open-source gehört und über den Schlüssel OS verfügt, in GitHub wie folgt benannt: OS-airports. Wenn ein Repository in GitHub einen anderen Namen haben soll, aktualisiere den Wert für das entsprechende Flag --github-repo.

Ausführen deines Migrationsskripts

Führe das generierte Skript aus, um deine Repositorys zu migrieren.

Dieser Schritt muss über einen Computer ausgeführt werden, der über Zugriff auf Folgendes verfügt:

• Deine Bitbucket Server-Instanz über HTTPS
• Deine Bitbucket Server-Instanz über SFTP, wenn deine Bitbucket Server-Instanz unter Linux ausgeführt wird. Allgemein gilt: Wenn du über SSH auf den Server zugreifen kannst, kannst du auch SFTP verwenden.
• Deine Bitbucket Server-Instanz über SMB, wenn deine Bitbucket Server-Instanz unter Windows ausgeführt wird
• Deinen ausgewählten Blobspeicheranbieter

Bevor du das Skript ausführst, musst du zusätzliche Umgebungsvariablen für die Authentifizierung bei deinem Blobspeicheranbieter festlegen.

• Lege für AWS S3 die folgenden Umgebungsvariablen fest.
  • AWS_ACCESS_KEY: Zugriffsschlüssel deines Buckets
  • AWS_SECRET_KEY: geheimer Schlüssel deines Buckets
  • AWS_REGION: Die AWS-Region, in der sich dein Bucket befindet
  • AWS_SESSION_TOKEN: Das AWS-Sitzungstoken, wenn du temporäre AWS-Anmeldeinformationen verwendest (siehe Verwenden temporärer Anmeldeinformationen mit AWS-Ressourcen in der AWS-Dokumentation)
• Lege für Azure Blob Storage AZURE_STORAGE_CONNECTION_STRING auf die Verbindungszeichenfolge für dein Azure Storage-Konto fest.

Only connection strings using storage account access keys are supported. Connection strings which use shared access signatures (SAS) are not supported. For more information about storage account access keys, see Manage storage account access keys in the Azure documentation.

Führe das oben generierte Skript aus, um mehrere Repositorys zu migrieren. Ersetze FILENAME in den folgenden Befehlen durch den Dateinamen, den du beim Generieren des Skripts angegeben hast.

• Wenn du ein Terminal verwendest, gibst du ./ ein.
  Shell

  ./FILENAME

• Wenn du PowerShell verwendest, gibst du .\ ein.
  Shell

  .\FILENAME