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

Pour voir les instructions d’utilisation de l’API, utilisez le sélecteur d’outils en haut de la page.

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

S’il s’agit de votre première migration, vous devez installer GEI 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-gei. Vous pouvez exécuter le 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 avez besoin de la version 2.4.0 ou d'une version plus récente de GitHub CLI. Vous pouvez vérifier la version que vous avez installée avec la commande gh --version.

2. Installez GEI extension.

   Shell

   gh extension install github/gh-gei
   

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

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

GEI extension est mis à 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-gei

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

Avant de pouvoir utiliser GEI extension pour migrer vers GitHub Enterprise Cloud, vous devez créer des personal access token qui peuvent accéder aux organisations source et de destination, puis définir les personal access token en tant que variables d’environnement.

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 entre des produits GitHub ».

2. Créez et enregistrez un personal access token qui servira d’authentification pour l’organisation source, en vous assurant qu’il répond également aux mêmes exigences.

3. Définissez les variables d’environnement pour les personal access token, en remplaçant TOKEN dans les commandes ci-dessous par les personal access token que vous avez enregistrés ci-dessus. Utilisez GH_PAT pour l’organisation de destination et GH_SOURCE_PAT pour l’organisation source.

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

     Shell

     export GH_PAT="TOKEN"
     export GH_SOURCE_PAT="TOKEN"
     

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

     Shell

     $env:GH_PAT="TOKEN"
     $env:GH_SOURCE_PAT="TOKEN"
     

4. Si vous migrez vers GitHub Enterprise Cloud avec résidence des données, pour des raisons pratiques, définissez une variable d'environnement pour l'URL de l'API de base de votre entreprise.

   Vérifiez que vous remplacez SUBDOMAIN par le sous-domaine de votre entreprise. Par exemple, si le sous-domaine de votre entreprise est acme, la TARGET_API_URL valeur est https://api.acme.ghe.com.

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

     Shell

     export TARGET_API_URL="https://api.SUBDOMAIN.ghe.com"
     

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

     Shell

     $env:TARGET_API_URL="https://api.SUBDOMAIN.ghe.com"
     

   Vous allez utiliser cette variable avec l’option --target-api-url dans les commandes que vous exécutez avec les données GitHub CLI.

Étape 4 : Configurer le stockage d’objets blob

Migrer des référentiels avec GitHub-owned blob storage

Si vous ne souhaitez pas configurer et fournir à GitHub Enterprise Importer un accès à un compte de stockage d'objets blob appartenant au client pour stocker vos archives de référentiel, vous pouvez migrer des référentiels à l'aide de GitHub-owned blob storage. Pour ce faire, vous devez exécuter la version v1.9.0 (ou ultérieure) de GEI extension of the GitHub CLI. GitHub-owned blob storage ne nécessite aucune configuration supplémentaire et est disponible en tant qu'option lorsque vous exécutez des commandes GEI extension of the GitHub CLI.

Pour des raisons de sécurité, GitHub-owned blob storage est explicitement en écriture seule, et les téléchargements depuis GitHub-owned blob storage ne sont pas possibles. Une fois une migration terminée, les archives de référentiel sont supprimées immédiatement. Si une archive est chargée et n'est pas utilisée dans une migration, l'archive est supprimée après 7 jours.

Lorsque vous utilisez l'indicateur CLI pour GitHub-owned blob storage, l'archive de référentiel est automatiquement exportée vers la destination configurée dans la Management Console, chargée vers le stockage appartenant à GitHub et importée vers votre destination de migration. Lorsque vous utilisez GitHub-owned blob storage, nous vous recommandons de configurer le stockage local. Veuillez consulter la section Utiliser le stockage local (GHES 3.16+).

Migrer des référentiels avec un stockage d'objets blob appartenant au client

Vous devez stocker vos données de référentiel dans un emplacement auquel GitHub peut accéder. Si votre instance GitHub Enterprise Server se trouve derrière un pare-feu, vous devrez peut-être configurer le stockage d’objets blob avec un service cloud externe.

Pour commencer, vous devez configurer le stockage d’objets blob avec un fournisseur pris en charge. Ensuite, si vous utilisez un fournisseur de cloud, vous devez configurer vos informations d’identification pour le fournisseur de stockage dans la Management Console ou GitHub CLI.

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

• Amazon Web Services (AWS) S3

• Stockage Blob Azure

• Stockage local sur l’instance GHES (GHES 3.16 et versions ultérieures). Nous vous recommandons d’utiliser cette option avec GitHub-owned blob storage.

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

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.

Utiliser le stockage local (GHES 3.16+)

Lorsque vous exécutez une migration avec un stockage local, les données d’archivage sont écrites sur le disque sur votre instance GitHub Enterprise Server, sans nécessiter un fournisseur de stockage cloud.

• Si vous ne disposez pas de règles de pare-feu bloquant le trafic sortant de GitHub Enterprise Server, GitHub Enterprise Importer peut automatiquement récupérer l’archive stockée à partir de GitHub Enterprise Server.
• Si vous avez mis en place des règles de pare-feu et que vous ne souhaitez pas autoriser l’accès à GitHub Enterprise Importer, vous pouvez télécharger vos données d’archive vers GitHub-owned blob storage afin que GitHub Enterprise Importer puisse y accéder. Pour le faire manuellement, consultez Téléchargement de vos archives de migration sur le stockage blob détenu par GitHub dans la version API de cet article.

1. À partir d’un compte d’administration sur GitHub Enterprise Server, cliquez sur en haut à droite de n’importe quelle page.
2. Dans la barre latérale « Site admin », cliquez sur Management Console.
3. Connectez-vous à la Management Console.
4. Dans la barre latérale gauche, cliquez sur Migrations.
5. Cliquez sur Activer les migrations GitHub.
6. Sous « Stockage des migrations », cliquez sur Stockage local.
7. Cliquez sur Enregistrer les paramètres.

Lorsque vous effectuez la migration, surveillez l’espace disque sur GitHub Enterprise Server. Les archives de migration sont automatiquement supprimés après 7 jours. Pour libérer de l’espace, vous pouvez supprimer une archive à l’aide de l' Points de terminaison d’API REST pour les migrations d’organisation.

Configuration de vos informations d’identification pour le stockage d’objets blob

Si vous configurez le stockage d'objets blob avec un fournisseur cloud (plutôt qu'avec le stockage local), vous devez configurer vos informations d'identification pour le fournisseur de stockage dans GitHub :

• Si vous utilisez GitHub Enterprise Server 3.8 ou ultérieur, configurez vos informations d’identification dans la Management Console.
• Si vous utilisez GitHub Enterprise Server 3.7 ou antérieur, configurez les informations d’identification dans GitHub CLI.

Configuration du stockage d’objets blob dans la Management Console de votre instance GitHub Enterprise Server

Après avoir configuré un compartiment de stockage AWS S3 ou un compte Stockage Blob Azure, configurez le stockage de blobs dans la Management Console de votre instance GitHub Enterprise Server. Pour plus d’informations sur la Management Console, consultez « Administration de votre instance à partir de la console de gestion ».

1. À partir d’un compte d’administration sur GitHub Enterprise Server, cliquez sur en haut à droite de n’importe quelle page.

2. Si vous n’êtes pas déjà sur la page « Administrateur du site », dans le coin supérieur gauche, cliquez sur Administrateur du site. 1. Dans la barre latérale « Site admin », cliquez sur Management Console.

3. Connectez-vous à la Management Console.

4. Dans la barre de navigation supérieure, cliquez sur Paramètres.

5. Sous Migrations, cliquez sur Activer les migrations GitHub .

6. Si vous le souhaitez, pour importer les paramètres de stockage que vous avez configurés pour GitHub Actions, sélectionnez Copier les paramètres de stockage dans Actions. Pour plus d’informations, consultez « Activation de GitHub Actions avec le Stockage Blob Azure » et « Activation de GitHub Actions avec le stockage Amazon S3 ».

   Remarque

   Après avoir copié vos paramètres de stockage, il se peut que vous deviez encore mettre à jour la configuration de votre compte de stockage en nuage pour qu'il fonctionne avec GitHub Enterprise Importer. Vous devez notamment vous assurer que les adresses IP de GitHub figurent dans la liste d'autorisation. Pour plus d’informations, consultez « Gestion de l’accès pour une migration entre des produits GitHub ».

7. Si vous n’importez pas les paramètres de stockage à partir de GitHub Actions, sélectionnez Stockage Blob Azure ou Amazon S3 et renseignez les détails requis.

   Remarque

   Si vous utilisez Amazon S3, vous devez définir « AWS Service URL » (URL du service AWS) sur le point de terminaison standard pour la région AWS où se trouve votre compartiment. Par exemple, si votre compartiment se trouve dans la région eu-west-1, « AWS Service URL » (URL du service AWS) est https://s3.eu-west-1.amazonaws.com. Le réseau de votre instance GitHub Enterprise Server doit autoriser l’accès à cet hôte. Les points de terminaison de passerelle ne sont pas pris en charge, tels que bucket.vpce-0e25b8cdd720f900e-argc85vg.s3.eu-west-1.vpce.amazonaws.com. Pour plus d’informations sur les points de terminaison de passerelle, consultez Points de terminaison de passerelle pour Amazon S3 dans la documentation AWS.

8. Cliquez sur Tester les paramètres de stockage.

9. Cliquez sur Enregistrer les paramètres.

Configuration de vos informations d’identification pour le stockage d’objets blob dans GitHub CLI

Configuration des informations d’identification AWS S3 dans GitHub CLI

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 des informations d’identification du compte Stockage Blob Azure dans GitHub CLI

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.

Autoriser l'accès au réseau

Si vous avez configuré des règles de pare-feu sur votre compte de stockage, assurez-vous d'avoir autorisé l'accès aux plages d'adresses IP de votre destination de migration. Consultez Gestion de l’accès pour une migration entre des produits GitHub.

Étape 5 : Générer un script de migration

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.

Si vous souhaitez migrer un seul dépôt, passez à l’étape suivante.

Génération d’un script de migration

Vous devez suivre cette étape à partir d’un ordinateur qui peut accéder à l’API pour votre instance GitHub Enterprise Server. Si vous pouvez accéder à votre instance à partir du navigateur, l’ordinateur dispose de l’accès approprié.

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

Pour GitHub Enterprise Server 3.8 ou version ultérieure, ou si vous utilisez la version 3.7 ou une version antérieure avec le Stockage Blob Azure, utilisez les indicateurs suivants :

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL

Si vous utilisez GitHub Enterprise Server 3.7 ou une version antérieure avec AWS S3, utilisez les indicateurs suivants :

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL \
  --aws-bucket-name AWS-BUCKET-NAME

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL \
  --aws-bucket-name AWS-BUCKET-NAME

Espaces réservés

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

Arguments supplémentaires

          **Avertissement:** Le verrouillage d’un référentiel source empêche d’autres modifications et peut perturber les flux de travail. Il est recommandé d’utiliser cette option uniquement si vous êtes certain qu’elle est appropriée. Pour plus d’informations, consultez « [AUTOTITLE](/migrations/overview/about-locked-repositories) ». |

| --no-ssl-verify | Si votre instance GitHub Enterprise Server utilise un certificat SSL auto-signé ou non valide, utilisez l’indicateur --no-ssl-verify. Avec cet indicateur, GitHub CLI ignore la vérification du certificat SSL lors de l’extraction des données de votre instance uniquement. Tous les autres appels vérifient SSL. | | --skip-releases | Si votre référentiel contient plus de 10 Go de données sur les versions, les versions ne peuvent pas être migrées. Utilisez l’indicateur --skip-releases pour migrer le dépôt sans les mises en production. | | --target-api-url TARGET-API-URL | Si vous migrez vers GHE.com, ajoutez --target-api-url TARGET-API-URL, où TARGET-API-URL est l'URL de l'API de base pour le sous-domaine de votre entreprise. Par exemple : https://api.octocorp.ghe.com. | | --use-github-storage| Effectue une migration de référentiel à l'aide de GitHub-owned blob storage comme solution intermédiaire de stockage d'objets blob. |

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.
• Si vous souhaitez que les dépôts aient un nom différent dans l’organisation de destination, mettez à jour la valeur de l’indicateur --target-repo correspondant.
• Si vous souhaitez modifier la visibilité d’un nouveau référentiel, mettez à jour la valeur de l’indicateur correspondant --target-repo-visibility . Par défaut, le script définit la même visibilité que le référentiel source.

Si votre référentiel contient plus de 10 Go de données sur les versions, les versions ne peuvent pas être migrées. Utilisez l’indicateur --skip-releases pour migrer le dépôt sans les mises en production.

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

Étape 6 : Migrer des dépôts

Vous pouvez migrer plusieurs dépôts à l’aide d’un script de migration ou un seul dépôt avec la commande gh gei migrate-repo.

Quand vous migrez des dépôts, l’GEI extension of the GitHub CLI effectue les étapes suivantes :

1. Se connecte à votre instance GitHub Enterprise Server et génère deux archives de migration par dépôt, une pour la source Git et une pour les métadonnées
2. Charge les archives de migration sur le fournisseur de stockage d’objets blob de votre choix
3. Démarre votre migration dans GitHub Enterprise Cloud à l’aide des URL des archives stockées avec votre fournisseur de stockage blob
4. Supprime l'archive de migration de votre machine locale

Migrer plusieurs dépôts

Si vous effectuez une migration à partir de GitHub Enterprise Server 3.7 ou version antérieure, avant d’exécuter votre script, vous devez définir des variables d’environnement supplémentaires pour vous authentifier sur votre fournisseur de stockage blob.

• 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 AWS S3, définissez les variables d’environnement suivantes. * AWS_ACCESS_KEY_ID : l'ID de clé d'accès de votre compartiment * AWS_SECRET_ACCESS_KEY : la clé secrète de votre compartiment * AWS_REGION : la région AWS où votre compartiment est situé * AWS_SESSION_TOKEN : le token de session, si vous utilisez des informations d'identification temporaires AWS (voir Utiliser des informations d'identification temporaires avec des ressources AWS dans la documentation AWS)

Pour migrer plusieurs référentiels, exécutez le script que vous avez généré. 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
  

Migrer un seul dépôt

Vous devez suivre cette étape à partir d’un ordinateur qui peut accéder à l’API pour votre instance GitHub Enterprise Server. Si vous pouvez accéder à votre instance à partir du navigateur, l’ordinateur dispose de l’accès approprié.

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

Si vous utilisez GitHub Enterprise Server 3.8 ou version ultérieure, utilisez les indicateurs suivants :

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL

Si vous effectuez une migration à partir de GitHub Enterprise Server 3.7 ou version antérieure et que vous utilisez le Stockage Blob Azure comme fournisseur de stockage blob, utilisez les indicateurs suivants pour vous authentifier :

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"

Si vous effectuez une migration à partir de GitHub Enterprise Server 3.7 ou version antérieure et que vous utilisez Amazon S3 comme fournisseur de stockage blob, utilisez les indicateurs suivants pour vous authentifier :

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"

Espaces réservés

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

Arguments supplémentaires

Abandon de la migration

gh gei abort-migration --migration-id MIGRATION-ID

gh gei abort-migration --migration-id MIGRATION-ID

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

Une fois votre migration terminée, nous vous recommandons de supprimer les archives de votre conteneur de stockage. Si vous prévoyez d’effectuer d’autres migrations, supprimez l’archive placée dans votre conteneur de stockage par l’ADO2GH extension. Si vous avez terminé la migration, vous pouvez supprimer l’intégralité du conteneur.