Migration de votre référentiel avec Enterprise Live Migrations

Prerequisites

Assurez-vous que vos environnements et développeurs sont prêts pour la migration. Consultez « Préparation de votre migration dynamique de GitHub Enterprise Server vers GHE.com ».

1. Configurer GitHub Enterprise Server

Vous devez définir une configuration sur l’instance GitHub Enterprise Server avant de créer des jetons et d’effectuer une migration. Ces valeurs de configuration s’appliquent à toutes les ELM migrations. Les développeurs sur GitHub Enterprise Server pourraient connaître un court temps d'arrêt lorsque vous appliquez la nouvelle configuration.

1. Accédez à l’interpréteur de commandes d’administration GitHub Enterprise Server via SSH. Consultez « Accès à l’interpréteur de commandes d’administration (SSH) ».

2. Définissez les variables de configuration suivantes avec ghe-config.

   Par exemple : ghe-config app.elm-exporter.enabled true

   Variable	Définissez cette valeur sur...
   app.elm-exporter.enabled	true
   app.elm.internal-webhooks-enabled	true
   app.elm-exporter.webhooks-loopback-address-enabled	true
   secrets.elm-exporter.migration-target-url	URL de l’API pour votre entreprise de destination (par exemple : https://api.octocorp.ghe.com). N’incluez pas de barre oblique finale dans l’URL.
   secrets.elm-exporter.source-user	Nom d’utilisateur associé au jeton de l’opérateur GitHub Enterprise Server . Il doit s’agir de votre nom d’utilisateur sur GitHub Enterprise Server; si quelqu’un d’autre va créer ce jeton, la valeur ici doit être définie sur son nom d’utilisateur. Nous vous recommandons d’utiliser l’utilisateur ghe-admin .

3. Appliquez la configuration.

   Shell

   ghe-config-apply
   

4. Quittez la session SSH. Vous allez exécuter le reste des commandes dans une session de terminal locale.

2. Créer des jetons d’opérateur avec accès d’entreprise

L’opérateur doit s’authentifier auprès de l’entreprise source et de destination avec un personal access token (classic). Pour obtenir des instructions sur la création de jetons, consultez Gestion de vos jetons d’accès personnels.

Veillez à noter les deux jetons, car vous en aurez besoin à l’étape suivante.

1. Sur GitHub Enterprise Server, créez un personal access token (classic) et sélectionnez l’étendue requise :

   • admin:enterprise

   Vous utiliserez ce jeton comme jeton source lors de la configuration du ELM CLI.

2. Sur GHE.com, créez un personal access token (classic) et sélectionnez les étendues requises :

   • admin:enterprise
   • admin:org

   Vous utiliserez ce jeton comme jeton cible lors de la configuration du ELM CLI.

3. Configurer l’outil de ligne de commande ELM

Vous allez exécuter la migration à partir d’une session de terminal local, à l’aide d’une extension du GitHub CLI.

1. Installez le GitHub CLI sur votre machine locale. Vous devez utiliser la version 2.0 ou ultérieure.

2. Installer l’extension ELM.

   Shell

   gh extension install github/gh-elm
   

3. Lancez l’Assistant Installation pour configurer l’extension.

   Shell

   gh elm configure
   

4. Suivez les instructions de l’Assistant Installation, en fournissant les URL d’API (par exemple : https://api.SUBDOMAIN.ghe.com) pour votre source et votre destination et les jetons que vous avez créés à l’étape précédente.

L’une de ces valeurs peut également être fournie en tant qu’indicateurs CLI sur n’importe quelle gh elm commande, qui prend la priorité sur la configuration. Par exemple : --target-url https://api.SUBDOMAIN.ghe.com.

Ce processus d’installation stocke les URL dans un fichier de configuration spécifique à la plateforme dans le répertoire de configuration de votre système d’exploitation, à l’adresse gh-elm/config.json. Les jetons d’accès seront stockés en toute sécurité dans le stockage secret de votre ordinateur.

4. Configurer les secrets de migration dynamiques

En plus des jetons d’opérateur ayant un accès d’entreprise, vous devez créer un personal access token (classic) pour les organisations source et cible. Vous devez répéter ces étapes pour chaque organisation à partir de laquelle vous migrez.

Créer des jetons d’accès

ELM doit s’authentifier auprès d’une personal access token (classic) pour la source et la destination de la migration. Pour obtenir des instructions sur la création de jetons, consultez Gestion de vos jetons d’accès personnels.

Veillez à noter ces jetons, car vous en aurez besoin à l’étape suivante.

1. Créez une personal access token (classic) sur GitHub Enterprise Server avec les portées suivantes :

   • repo
   • admin:org
   • admin:repo_hook
   • admin:org_hook

   Il s’agit de votre jeton source.

2. Créez une personal access token (classic) sur GHE.com avec les portées suivantes :

   • repo
   • workflow
   • admin:org
   • admin:repo_hook
   • admin:enterprise

   Il s’agit de votre jeton cible.

   Important

   Si l’authentification unique est imposée pour l’organisation cible sur GHE.com, vous devez autoriser le jeton GHE.com pour l’authentification unique.

Configurer les secrets de votre organisation ELM

Utilisez les commandes pour définir les gh elm config jetons d’accès source et cible :

1. Définissez le jeton source.

   Shell

   gh elm config set-source-pat EXISTING-GHES-ORG
   

   Collez le jeton source dans le terminal lorsque vous y êtes invité.

2. Définissez le jeton cible.

   Shell

   gh elm config set-target-pat EXISTING-GHES-ORG
   

   Collez le jeton cible dans le terminal quand vous y êtes invité.

Vous pouvez également définir les jetons de manière interactive, à l’aide gh elm config org-tokens EXISTING-GHES-ORGou dans les paramètres de votre organisation à l’adresse https://GHES_HOSTNAME/organizations/EXISTING-GHES-ORG/settings/secrets/elm-exporter/.

5. Créer une migration

Créez une migration en spécifiant les détails du référentiel source et cible.

gh elm migration create \
  --source-org EXISTING-GHES-ORG \
  --source-repo EXISTING-GHES-REPO \
  --target-org GHEC-ORG \
  --target-repo NEW-GHEC-REPO

gh elm migration create \
  --source-org EXISTING-GHES-ORG \
  --source-repo EXISTING-GHES-REPO \
  --target-org GHEC-ORG \
  --target-repo NEW-GHEC-REPO

Par exemple:

gh elm migration create \
  --source-org my-ghes-org \
  --source-repo my-ghes-repo \
  --target-org my-dr-org \
  --target-repo my-dr-repo

Indicateurs facultatifs :

• --start: si vous êtes prêt à démarrer la migration immédiatement.
• --target-visibility: les référentiels migrés sont créés avec une visibilité interne par défaut, mais vous pouvez spécifier private.

Enregistrer l’ID de migration

Vous devez voir une réponse semblable à ce qui suit :

{
  "migrationId": "2b5c9eae-b5da-4306-ab04-2a29cc2b7cb9",
  "expiresAt": "2026-02-11T21:49:33.619162159Z"
}

Exportez la migrationId variable en tant que variable, car vous en aurez besoin pour les commandes suivantes. Par exemple:

export MIGRATION_ID='2b5c9eae-b5da-4306-ab04-2a29cc2b7cb9'

6. Démarrer la migration

Si vous n’avez pas déjà démarré la migration, démarrez-la maintenant à l’aide de l’ID de migration que vous venez d’enregistrer.

gh elm migration start --migration-id $MIGRATION_ID

gh elm migration start --migration-id $MIGRATION_ID

Cela lance les processus de remplissage et de mise à jour dynamique. ELM collecte désormais des données à partir du référentiel source et surveille les événements webhook pris en charge.

7. Surveiller la migration

Une fois la migration démarrée, vous devez voir un nouveau référentiel sur GHE.com. Pendant la migration, vous verrez le dépôt remplir avec une charge initiale de données et recevoir des mises à jour lorsque les développeurs continuent à travailler dans le référentiel source.

Vous pouvez surveiller la progression de la migration de manière interactive à l’aide de la watch commande :

gh elm migration watch $MIGRATION_ID

Cela interroge l’API d’état de migration et affiche une interface utilisateur de texte auto-actualisante qui reflète la progression actuelle.

Supervision par programmation à l’aide de migration status

Si vous souhaitez qu’un état de migration convient à l’automatisation, utilisez la status commande :

gh elm migration status --migration-id $MIGRATION_ID

gh elm migration status --migration-id $MIGRATION_ID

L’indicateur le plus important dans la réponse est l’état de l’objet combinedState . Lorsque l’état atteint COMBINED_STATUS_READY_FOR_CUTOVER, vous devez être prêt à passer à l’étape suivante. Toutefois, vous serez averti dans le displayMessage si des ressources individuelles n'ont pas pu migrer, que vous devrez peut-être examiner.

Par exemple:

  "combinedState":  {
    "status":  "COMBINED_STATUS_READY_FOR_CUTOVER",
    "displayMessage":  "Ready for cutover (1 resources failed)",
    "repositories":  [
      {
        "repositoryNwo":  "new-test-org/my-new-repo",
        "phase":  "REPOSITORY_PHASE_READY_FOR_CUTOVER",
        "displayStatus":  "Ready for cutover (1 failed)"
      }
    ],
    "readyForCutover":  true,
    "cutoverBlockers":  []
  },

Conseils :

• Si vous exécutez plusieurs migrations, vous pouvez vérifier l’état de toutes ces dernières gh elm migration list. Cette commande affiche les migrations en cours par défaut, mais vous pouvez également filtrer par --status.
• Si vous rencontrez des statuts d'erreur qui nécessitent une attention particulière, consultez Résolution des problèmes de migrations dynamiques de GitHub Enterprise Server vers GHE.com.

8. Terminer la migration

Quand une migration est prête pour la transition, vous pouvez effectuer la migration. Le processus de basculement archivera le référentiel source, le rendant définitivement en lecture seule, sauf si un administrateur du référentiel le désarchive.

gh elm migration cutover --migration-id $MIGRATION_ID

gh elm migration cutover --migration-id $MIGRATION_ID

Continuez à surveiller la migration. Lorsque vous voyez l’état MIGRATION_STATUS_COMPLETED en haut de la réponse, la migration est terminée, bien qu’il existe des tâches de suivi permettant d’accorder l’accès aux utilisateurs à partir de GitHub Enterprise Server.

Étapes suivantes

Donnez aux utilisateurs l’accès au nouveau référentiel et rapprochez l’activité avec les comptes d’utilisateur. Consultez « Fin de votre migration dynamique de GitHub Enterprise Server vers GHE.com ».