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

• Pour veiller à bien comprendre les limitations connues du support de l’importateur, consultez « À propos de GitHub Enterprise Importer ».
• 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 bonnes pratiques relatives aux exécutions d’essai, consultez « Préparation à l’exécution d’une migration avec GitHub Enterprise Importer ».
• 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 « Octroi du rôle de migrateur pour GitHub Enterprise Importer ».
• 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 ».

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. To make sure you're using the latest version, update the extension.

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 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 GitHub Enterprise Importer ».

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 et d’une clé secrète AWS avec un accès read-write à votre compartiment.

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.

When you're ready to run your migration, you can either pass your connection string into the GitHub CLI as an argument, or pass it in using an environment variable called 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

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

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

Espace réservé | Valeur | ----------- | ----- | BBS-SERVER-URL | URL de votre instance Bitbucket Server PROJECT | The key for the Bitbucket Server project of the repository you want to migrate CURRENT-NAME | The name of the repository you want to migrate DESTINATION | Nom de l’organisation de destination NEW-NAME | Nom que vous souhaitez donner au dépôt migré SSH-USER | Si votre instance Bitbucket Server s’exécute sur Linux, nom d’utilisateur à utiliser pour la connexion à votre instance Bitbucket Server via SFTP PATH-TO-KEY | Si votre instance Bitbucket Server s’exécute sur Linux, chemin de votre clé privée SSH, par exemple ~/.ssh/id_rsa. Pour connaître les exigences en termes de clés SSH, consultez « Gestion de l’accès pour GitHub Enterprise Importer ». SMB-USER | Si votre instance Bitbucket Server s’exécute sur Windows, nom d’utilisateur à utiliser lors de la connexion à votre Bitbucket Server via SMB AWS-BUCKET-NAME | Nom de compartiment pour votre compartiment AWS S3

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

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

Espace réservé | Valeur | ----------- | ----- | BBS-SERVER-URL | URL de votre instance Bitbucket Server PROJECT | The key for the Bitbucket Server project of the repository you want to migrate CURRENT-NAME | The name of the repository you want to migrate

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 \
  # 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.

Espace réservé | Valeur | ----------- | ----- | ARCHIVE-PATH | Chemin d’accès à l’archive de migration Bitbucket Server que vous avez téléchargée à partir de votre instance DESTINATION | Nom de l’organisation de destination NEW-NAME | Nom que vous souhaitez donner au dépôt migré AWS-BUCKET-NAME | Nom de compartiment pour votre compartiment AWS S3

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

When your migration is complete, we recommend reviewing your migration log. For more information, see "Accès à vos journaux de migration pour GitHub Enterprise Importer."

We recommend that you review your migrated repositories for a soundness check.

É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

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.

Espace réservé | Valeur | ----------- | ----- | BBS-SERVER-URL | URL de votre instance Bitbucket Server DESTINATION | Nom de l’organisation de destination FILENAME | Nom de fichier du script de migration résultant

Si vous utilisez le Terminal, choisissez une extension de fichier .ps1, car le script généré exige l’exécution de PowerShell. Vous pouvez installer PowerShell pour Mac ou Linux. SSH-USER | Si votre instance Bitbucket Server s’exécute sur Linux, nom d’utilisateur à utiliser pour la connexion à votre instance Bitbucket Server via SFTP PATH-TO-KEY | Si votre instance Bitbucket Server s’exécute sur Linux, chemin de votre clé privée SSH, par exemple ~/.ssh/id_rsa. Pour connaître les exigences en termes de clés SSH, consultez « Gestion de l’accès pour GitHub Enterprise Importer ». SMB-USER | Si votre instance Bitbucket Server s’exécute sur Windows, nom d’utilisateur à utiliser lors de la connexion à votre Bitbucket Server via SMB

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.

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 : clé d’accès de votre compartiment
  • AWS_SECRET_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