Migration de dépôts de Bitbucket Server vers GitHub Enterprise Cloud

À propos des migrations de dépôts avec GitHub Enterprise Importer

Vous pouvez migrer des dépôts individuels ou tous les dépôts à partir d’une instance BitBucket Server en utilisant l’GitHub CLI.

À l’heure actuelle, la migration à partir de Bitbucket Server avec l’API GitHub n’est pas prise en charge.

Prérequis

• Nous vous recommandons vivement d’effectuer une exécution d’essai de votre migration et d’effectuer votre migration de production peu après. Pour en savoir plus sur les exécutions d’essai, consultez « Vue d’ensemble d’une migration de Bitbucket Server vers GitHub Enterprise Cloud ».
• Assurez-vous que vous comprenez les données qui seront migrées et les limitations de prise en charge connues de l’importateur. Pour plus d’informations, consultez « Informations sur les migrations de Bitbucket Server vers GitHub Enterprise Cloud ».
• Bien que cela ne soit pas obligatoire, nous vous recommandons d’interrompre votre travail pendant votre migration de production. Importer ne prend pas en charge les migrations delta, donc aucune modification apportée pendant la migration ne sera migrée. Si vous choisissez de ne pas interrompre le travail pendant votre migration de production, vous devrez migrer manuellement ces modifications.
• Pour l’organisation de destination sur GitHub.com, vous devez être propriétaire d’organisation ou avoir le rôle Migrateur. Pour plus d’informations, consultez « Gestion de l’accès pour une migration à partir de Bitbucket Server ».
• Vous avez besoin du nom d’utilisateur et du mot de passe d’un compte Bitbucket Server avec des autorisations d’administrateur ou de super administrateur.

Étape 1 : Installer l’BBS2GH extension of the GitHub CLI

S’il s’agit de votre première migration, vous devez installer l’BBS2GH extension of the GitHub CLI. Pour plus d’informations sur GitHub CLI, consultez « À propos de GitHub CLI ».

Vous pouvez également télécharger un fichier binaire autonome à partir de la page des versions du référentiel github/gh-bbs2gh. Vous pouvez exécuter ce fichier binaire directement, sans le préfixe gh.

1. Installez GitHub CLI. Pour obtenir des instructions d’installation pour GitHub CLI, consultez le dépôt GitHub CLI.

   Remarque : Vous devez avoir la version 2.4.0 ou ultérieure de GitHub CLI. Vous pouvez vérifier la version que vous avez installée avec la commande gh --version.

2. Installez l’BBS2GH extension.

   Shell

   gh extension install github/gh-bbs2gh
   

Dès que vous avez besoin d’aide sur BBS2GH extension, vous pouvez utiliser l’indicateur --help avec une commande. Par exemple, gh bbs2gh --help liste toutes les commandes disponibles et gh bbs2gh migrate-repo --help liste toutes les options disponibles pour la commande migrate-repo.

Étape 2 : Mettre à jour l’BBS2GH extension of the GitHub CLI

L’BBS2GH extension of the GitHub CLI est mise à jour toutes les semaines. Pour être sûr d’utiliser la version la plus récente, mettez à jour l’extension.

gh extension upgrade github/gh-bbs2gh

gh extension upgrade github/gh-bbs2gh

Étape 3 : Définir les variables d’environnement

Avant de pouvoir utiliser l’BBS2GH extension pour migrer vers GitHub Enterprise Cloud, vous devez créer un personal access token pouvant accéder à l’organisation de destination, puis définir le personal access token dans une variable d’environnement.

Vous devez également définir des variables d’environnement pour le nom d’utilisateur et le mot de passe de votre instance Bitbucket Server et, si elle s’exécute sur Windows, votre mot de passe SMB.

1. Créez et enregistrez un personal access token (classic) qui servira d’authentification pour l’organisation de destination sur GitHub Enterprise Cloud, en vous assurant qu’il répond à toutes les exigences. Pour plus d’informations, consultez « Gestion de l’accès pour une migration à partir de Bitbucket Server ».

2. Définissez des variables d’environnement, en remplaçant TOKEN par le personal access token que vous avez enregistré ci-dessus, USERNAME par le nom d’utilisateur d’un compte Bitbucket Server avec des autorisations d’administrateur ou de super administrateur, et PASSWORD par le mot de passe du compte Bitbucket Server.

   • Si vous utilisez le Terminal, utilisez la commande export.

     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"
     

   • Si vous utilisez PowerShell, utilisez la commande $env.

     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"
     

Étape 4 : Configurer le stockage d’objets blob

Comme de nombreuses instances Bitbucket Server se trouvent derrière des pare-feu, l’GitHub CLI utilise le stockage blob comme emplacement intermédiaire pour stocker vos données accessibles sur Internet.

Vous allez d’abord générer une archive des données que vous souhaitez migrer et pousser les données dans le stockage blob derrière votre pare-feu.

GitHub CLI prend en charge les fournisseurs de stockage de blobs suivants :

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

Avant d’exécuter une migration, vous devez configurer un conteneur de stockage avec le fournisseur de cloud de votre choix pour stocker vos données.

Configuration d’un compartiment de stockage AWS S3

Dans AWS, configurez un compartiment S3. Pour plus d’informations, consultez Créer un compartiment dans la documentation AWS.

Vous aurez également besoin d’une clé d’accès AWS et d’une clé secrète avec les autorisations suivantes :

{
    "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/*"
            ]
        }
    ]
}

Quand vous êtes prêt à exécuter votre migration, vous devez fournir vos informations d’identification AWS à l’GitHub CLI : région, clé d’accès, clé secrète et jeton de session (si nécessaire). Vous pouvez les passer comme des arguments ou définir des variables d’environnement appelées AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY et AWS_SESSION_TOKEN.

Vous devez également passer le nom du compartiment S3 en utilisant l’argument --aws-bucket-name.

Configuration d’un compte Stockage Blob Azure

Dans Azure, créez un compte de stockage et notez votre chaîne de connexion. Pour plus d’informations, consultez Gérer les clés d’accès au compte de stockage dans Microsoft Docs.

Lorsque vous êtes prêt à exécuter votre migration, vous pouvez passer votre chaîne de connexion à GitHub CLI en tant qu’argument, ou la passer en utilisant une variable d’environnement appelée AZURE_STORAGE_CONNECTION_STRING.

Étape 5 : Migrer un dépôt

Vous pouvez migrer des référentiels avec la commande gh bbs2gh migrate-repo.

Quand vous migrez un dépôt, par défaut, l’BBS2GH extension of the GitHub CLI effectue les étapes suivantes :

1. Elle se connecte à votre instance Bitbucket Server et génère une archive de migration par dépôt
2. Elle télécharge l’archive de migration à partir de l’instance Bitbucket Server sur la machine où vous exécutez l’BBS2GH extension of the GitHub CLI, en utilisant SFTP (Linux) ou SMB (Windows)
3. Charge les archives de migration sur le fournisseur de stockage d’objets blob de votre choix
4. Démarre votre migration dans GitHub Enterprise Cloud à l’aide des URL des archives stockées avec votre fournisseur de stockage blob
5. Supprime l’archive de migration de votre ordinateur local. (Vous devez supprimer manuellement l’archive de votre fournisseur de stockage blob une fois la migration terminée.)

Vous pouvez également utiliser GitHub CLI pour générer l’archive, télécharger cette archive manuellement, puis utiliser GitHub CLI pour poursuivre la migration.

• « Autoriser GitHub CLI à télécharger l’archive de migration »
• « Téléchargement manuel de l’archive de migration »

Autoriser GitHub CLI à télécharger l’archive de migration

Pour migrer un seul dépôt, utilisez la commande gh bbs2gh migrate-repo.

Vous devez suivre cette étape sur un ordinateur avec un accès à :

• Votre instance Bitbucket Server via HTTPS
• Votre instance Bitbucket Server via SFTP, si elle s’exécute sur Linux. En général, si vous pouvez accéder au serveur via SSH, vous pouvez également utiliser SFTP.
• Votre instance Bitbucket Server via SMB, si elle s’exécute sur Windows
• Le fournisseur de stockage blob de votre choix

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

Remplacez les espaces réservés dans la commande ci-dessus par les valeurs suivantes.

Téléchargement manuel de l’archive de migration

Par défaut, BBS2GH extension of the GitHub CLI effectue l’intégralité de la migration, y compris le téléchargement de l’archive de migration à partir de l’instance Bitbucket Server à l’aide de SFTP ou de SMB.

Toutefois, certains clients préfèrent télécharger manuellement l’archive de migration, car leur serveur n’offre pas d’accès SFTP, par exemple. Dans ce cas, vous pouvez utiliser GitHub CLI pour générer l’archive, télécharger cette archive manuellement, puis utiliser GitHub CLI pour poursuivre la migration.

Vous devez suivre cette étape sur un ordinateur avec un accès à :

• Votre instance Bitbucket Server via HTTPS
• Le fournisseur de stockage blob de votre choix

Tout d’abord, utilisez la commande gh bbs2gh migrate-repo avec uniquement les arguments suivants :

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

Remplacez les espaces réservés dans la commande ci-dessus par les valeurs suivantes.

Votre archive de migration est générée, et son chemin d’accès est imprimé dans la sortie de commande :

[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

En général, $BITBUCKET_SHARED_HOME sera défini sur /var/atlassian/application-data/bitbucket/shared sur Linux et C:\Atlassian\ApplicationData\Bitbucket\Shared sur Windows, mais cela peut différer en fonction de la configuration de votre serveur. Pour vous aider à identifier votre répertoire partagé de base, consultez « Résolution des problèmes de votre migration avec GitHub Enterprise Importer ».

Téléchargez l’archive de migration à partir de votre instance Bitbucket Server et stockez l’archive sur l’ordinateur sur lequel vous exécutez GitHub CLI.

Pour importer votre archive de migration dans GitHub, utilisez à nouveau la commande gh bbs2gh migrate-repo, avec un autre ensemble d’arguments :

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

Remplacez les espaces réservés dans la commande ci-dessus par les valeurs suivantes.

Annulation de la migration

Si vous souhaitez annuler une migration, utilisez la commande abort-migration, en remplaçant MIGRATION-ID par l'ID retourné par migrate-repo.

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

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

Étape 6 : Valider votre migration et consulter le journal des erreurs

Une fois votre migration terminée, nous vous recommandons d’examiner votre journal de migration. Pour plus d’informations, consultez « Accès à vos journaux de migration pour GitHub Enterprise Importer ».

Nous vous recommandons de passer en revue vos dépôts migrés pour en contrôler l’intégrité.

Étape 7 : Migrer plusieurs dépôts

Si vous souhaitez migrer simultanément plusieurs dépôts vers GitHub Enterprise Cloud, utilisez GitHub CLI pour générer un script de migration. Le script résultant contiendra une liste de commandes de migration, une par dépôt.

Génération d’un script de migration

Vous devez suivre cette étape à partir d’un ordinateur pouvant accéder à votre instance Bitbucket Server via HTTPS.

Pour générer un script de migration, exécutez la commande gh bbs2gh generate-script.

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

Si vous souhaitez que le script télécharge le journal de migration pour chaque dépôt migré, ajoutez l’indicateur --download-migration-logs. Pour plus d’informations sur les journaux de migration, consultez « Accès à vos journaux de migration pour GitHub Enterprise Importer ».

Remplacez les espaces réservés dans la commande ci-dessus par les valeurs suivantes.

Examen du script de migration

Après avoir généré le script, passez en revue le fichier et, éventuellement, modifiez le script.

• S’il y a des dépôts que vous ne souhaitez pas migrer, supprimez ou commentez les lignes correspondantes.
• Par défaut, les noms de dépôt dans GitHub suivent la convention projectKey-repositoryName. Par exemple, un dépôt Bitbucket Server nommé airports faisant partie du projet open-source, qui a la clé OS, est appelé OS-airports dans GitHub. Si vous voulez changer le nom des dépôts sur GitHub, mettez à jour la valeur de l’indicateur --github-repo correspondant.

Si vous avez téléchargé BBS2GH en tant que fichier binaire autonome plutôt qu’en tant qu’extension de GitHub CLI, vous devrez mettre à jour votre script généré pour exécuter le fichier binaire au lieu de gh bbs2gh.

Exécution de votre script de migration

Pour migrer vos dépôts, exécutez le script généré.

Vous devez suivre cette étape sur un ordinateur avec un accès à :

• Votre instance Bitbucket Server via HTTPS
• Votre instance Bitbucket Server via SFTP, si elle s’exécute sur Linux. En général, si vous pouvez accéder au serveur via SSH, vous pouvez également utiliser SFTP.
• Votre instance Bitbucket Server via SMB, si elle s’exécute sur Windows
• Le fournisseur de stockage blob de votre choix

Avant d’exécuter le script, vous devez définir des variables d’environnement supplémentaires pour vous authentifier auprès de votre fournisseur de stockage d’objets blob.

• Pour AWS S3, définissez les variables d’environnement suivantes.
  • AWS_ACCESS_KEY_ID : ID de clé d’accès de votre compartiment
  • AWS_SECRET_ACCESS_KEY : clé secrète de votre compartiment
  • AWS_REGION : région AWS où se trouve votre compartiment
  • AWS_SESSION_TOKEN : jeton de session, si vous utilisez des informations d’identification AWS temporaires (consultez Utilisation d’informations d’identification temporaires avec des ressources AWS dans la documentation AWS)
• Pour Stockage Blob Azure, définissez AZURE_STORAGE_CONNECTION_STRING avec la chaîne de connexion de votre compte de stockage Azure.

Seules les chaînes de connexion utilisant des clés d’accès au compte de stockage sont prises en charge. Les chaînes de connexion qui utilisent des signatures d’accès partagé (SAS) ne sont pas prises en charge. Pour plus d’informations sur les clés d’accès au compte de stockage, consultez Gérer les clés d’accès au compte de stockage dans la documentation Azure.

Pour migrer plusieurs dépôts, exécutez le script que vous avez généré ci-dessus. Remplacez FILENAME dans les commandes ci-dessous par le nom de fichier que vous avez fourni lors de la génération du script.

• Si vous employez le Terminal, utilisez ./.

  Shell

  ./FILENAME
  

• Si vous employez PowerShell, utilisez .\.

  Shell

  .\FILENAME