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

• Es wird dringend empfohlen, einen Testlauf deiner Migration durchzuführen und die Produktionsmigration bald danach abzuschließen. Mehr über Testläufe erfahren Sie unter Übersicht über die Migration von Butbucket Server zu GitHub Enterprise Cloud.
• Stellen Sie sicher, dass Sie die zu migrierenden Daten und die bekannten Supportbeschränkungen des Importer verstehen. Weitere Informationen finden Sie unter Informationen zu Migrationen von Butbucket Server zu GitHub Enterprise Cloud.
• 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 Verwalten des Zugriffs für eine Migration von Bitbucket Server.
• 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.

Alternativ können Sie eine eigenständige Binärdatei von der Veröffentlichungsseite für das github/gh-bbs2gh-Repository herunterladen. Sie können diese Binärdatei direkt ohne das gh-Präfix ausführen.

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
   

Wenn du Hilfe zur BBS2GH extension benötigst, kannst du immer das Flag --help mit einem Befehl verwenden. Mit gh bbs2gh --help listest du z. B. alle verfügbaren Befehle auf, und mit gh bbs2gh migrate-repo --help zeigst du alle Optionen an, die für den Befehl migrate-repo verfügbar sind.

Schritt 2: Aktualisieren der BBS2GH extension of the GitHub CLI

Die BBS2GH extension of the GitHub CLI wird wöchentlich aktualisiert. Aktualisieren die Erweiterung, um sicherzustellen, dass du die neueste Version verwendest.

gh extension upgrade github/gh-bbs2gh

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 (classic) 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 eine Migration von Bitbucket Server.

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 den folgenden Berechtigungen:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::github-migration-bucket",
                "arn:aws:s3:::github-migration-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 von deinem lokalen Computer (Nach Abschluss der Migration musst du das Archiv manuell aus deinem Blobspeicheranbieter löschen.)

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
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

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
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.

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

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.

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 \
  --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME \
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-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.

Abbrechen einer Migration

Wenn Sie eine Migration abbrechen möchten, verwenden Sie den Befehl abort-migration und ersetzen Sie die MIGRATIONS-ID durch die zurückgesendete ID migrate-repo.

gh bb2gh abort-migration --migration-id MIGRATION-ID

gh bb2gh abort-migration --migration-id MIGRATION-ID

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

Wenn du mehrere Repositorys gleichzeitig zu GitHub Enterprise Cloud migrieren möchtest, verwendest du die GitHub CLI, um ein Migrationsskript zu generieren. Das resultierende Skript enthält eine Liste von Migrationsbefehlen (einen pro 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
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

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
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

Wenn das Skript das Migrationsprotokoll für jedes migrierte Repository herunterladen soll, fügst du das Flag --download-migration-logs hinzu. Weitere Informationen zu Migrationsprotokollen findest du unter Zugreifen auf die Migrationsprotokolle für GitHub Enterprise Importer.

Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.

Ü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.

Wenn Sie BBS2GH als eigenständige Binärdatei heruntergeladen haben und nicht als Erweiterung für die GitHub CLI, müssen Sie das generierte Skript aktualisieren, um die Binärdatei anstelle von gh bbs2gh auszuführen.

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.

Es werden nur Verbindungszeichenfolgen mit Zugriffsschlüsseln für Speicherkonten unterstützt. Verbindungszeichenfolgen, die Shared Access Signatures (SAS) verwenden, werden nicht unterstützt. Weitere Informationen zu Zugriffsschlüsseln für Speicherkonten findest du unter Verwalten von Speicherkonto-Zugriffsschlüsseln in der Azure-Dokumentation.

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