Migration d’organisations de GitHub.com vers GitHub Enterprise Cloud

À propos des migrations d’organisations avec GitHub Enterprise Importer

Les migrations vers GitHub Enterprise Cloud incluent des migrations entre les comptes sur GitHub.com et, si vous adoptez différente, les migrations vers le sous-domaine de votre entreprise de GHE.com.

Vous pouvez exécuter votre migration avec GitHub CLI ou l’API.

GitHub CLI simplifie le processus de migration et est recommandé pour la plupart des clients. Les clients avancés avec de grands besoins de personnalisation peuvent utiliser l’API pour créer leurs propres intégrations avec GitHub Enterprise Importer.

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

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

Si l’organisation de destination ou l’entreprise a des ensembles de règles activés, l’historique du référentiel migré peut violer ces règles. Pour autoriser la migration sans désactiver vos ensembles de règles, ajoutez « Migrations de référentiels » à la liste de contournement pour chaque ensemble de règles applicable. Ce contournement s’applique uniquement pendant la migration. Une fois terminés, les ensembles de règles seront appliqués à toutes les nouvelles contributions.

Pour configurer le contournement :

Accédez à chaque ensemble de règles d’entreprise ou d’organisation.
Dans la section « Liste de contournement », cliquez sur Ajouter un contournement.
Sélectionnez Migrations de référentiels.

Pour plus d’informations, consultez « Création d'ensembles de règles pour les dépôts de votre organisation ».

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 entre produits GitHub.
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, veuillez consulter la section Informations sur les migrations entre les produits GitHub.
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 source, vous devez être propriétaire d’organisation ou avoir le rôle de migrateur. Pour plus d’informations, consultez « Gestion de l’accès pour une migration entre des produits GitHub ».
Pour le compte d’entreprise de destination, vous devez être propriétaire d’entreprise.
Les migrations d’organisations peuvent migrer des organisations comptant jusqu’à 5 000 référentiels. Si une organisation compte plus de 5 000 référentiels, suivez les instructions de Migration de dépôts de GitHub.com vers GitHub Enterprise Cloud.

Étape 0 : Se préparer pour utiliser l’API GraphQL GitHub

Pour créer des requêtes GraphQL, vous devez écrire vos propres scripts ou utiliser un client HTTP comme Insomnia.

Pour en savoir plus sur l’utilisation de l’API GraphQL GitHub, notamment sur la façon de s’authentifier, consultez Formation d’appels avec GraphQL.

Vous enverrez toutes les requêtes GraphQL à la destination de votre migration. Si vous migrez vers GitHub Enterprise Cloud avec résidence des données, veillez à envoyer des requêtes au point de terminaison du sous-domaine de votre entreprise, GHE.com.

Étape 1 : Obtenir l’ID d’entreprise de la destination de votre migration

En tant que propriétaire d’entreprise sur GitHub.com, utilisez la requête suivante pour retourner l’ID de compte d’entreprise que vous souhaitez posséder pour l’organisation migrée. Vous avez besoin de l’ID d’entreprise pour identifier votre destination de migration.

query(
  $slug: String!
){
  enterprise (slug: $slug)
  {
    slug
    id
  }
}

Variable de requête	Description
`slug`	L'identifiant de votre compte d'entreprise, que vous pouvez identifier en regardant l'URL de votre entreprise `https://github.com/enterprises/SLUG` ou `https://SLUG.ghe.com`.

Étape 2 : Démarrer votre migration d’organisation

Lorsque vous démarrez une migration, une seule organisation et ses données associées migrent vers une toute nouvelle organisation dans l’entreprise de destination que vous identifiez.

mutation startOrganizationMigration (
  $sourceOrgUrl: URI!,
  $targetOrgName: String!,
  $targetEnterpriseId: ID!,
  $sourceAccessToken: String!,
    $targetAccessToken: String!
){
  startOrganizationMigration( input: {
    sourceOrgUrl: $sourceOrgUrl,
    targetOrgName: $targetOrgName,
    targetEnterpriseId: $targetEnterpriseId,
    sourceAccessToken: $sourceAccessToken,
        targetAccessToken: $targetAccessToken
  }) {
    orgMigration {
      id
    }
  }
}

Variable de requête	Description
`sourceOrgUrl`	URL de l’organisation source, par exemple `https://github.com/octo-org`.
`targetOrgName`	Nom que vous souhaitez que la nouvelle organisation porte. Ne peut pas être partagé par une autre organisation sur votre plateforme de destination.
`targetEnterpriseId`	ID de l’entreprise dans laquelle vous souhaitez créer la nouvelle organisation, retourné à l’étape 2.
`sourceAccessToken`	Votre personal access token (classic) pour l’organisation source. Pour connaître les conditions requises, consultez Gestion de l’accès pour une migration entre des produits GitHub.
`targetAccessToken`	Votre personal access token (classic) pour l’entreprise de destination.

À l’étape suivante, vous allez utiliser l’ID de migration retourné par la mutation startOrganizationMigration pour vérifier l’état de la migration.

Étape 3 : Vérifier l’état de votre migration

Pour détecter les échecs de migration et vous assurer que votre migration fonctionne, vous pouvez interroger la ou les mutations OrganizationMigration que vous avez créées pour voir l’état de la migration à l’aide de la requête getMigration.

La requête est retournée avec un état qui vous indique si la migration est queued, in progress, failed ou completed, ainsi que des informations sur le nombre de dépôts en attente de migration. Si votre migration a échoué, Importer fournit la raison de l’échec.

query (
  $id: ID!
){
  node( id: $id ) {
    ... on OrganizationMigration {
      id
            sourceOrgUrl
            targetOrgName
      state
      failure_reason
      remaining_repositories_count
      total_repositories_count
    }
  }
}

Variable de requête	Description
`id`	`id` de votre migration.

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

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.

Installez GEI extension.

Shell

gh extension install github/gh-gei

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 tokens (classic) qui peuvent accéder à l’organisation source et à l’entreprise de destination, puis définir les personal access tokens (classic) comme variables d’environnement.

Créez et enregistrez un personal access token qui répond à toutes les conditions requises d’authentification pour l’organisation source pour les migrations d’organisation. Pour plus d’informations, consultez « Gestion de l’accès pour une migration entre des produits GitHub ».
Créez et enregistrez un personal access token (classic) qui répond à toutes les conditions requises d’authentification pour l’entreprise de destination pour les migrations d’organisation.
Définissez les variables d’environnement pour les personal access tokens (classic), en remplaçant TOKEN dans les commandes ci-dessous par les personal access tokens (classic) que vous avez enregistrés ci-dessus. Utilisez GH_PAT pour l’entreprise 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"
```
```
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"
```
```
$env:GH_PAT="TOKEN"
$env:GH_SOURCE_PAT="TOKEN"
```
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"
```
```
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"
```
```
$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 : Migrer votre organisation

Pour migrer une organisation, utilisez la commande gh gei migrate-org.

Shell

gh gei migrate-org --github-source-org SOURCE --github-target-org DESTINATION --github-target-enterprise ENTERPRISE

gh gei migrate-org --github-source-org SOURCE --github-target-org DESTINATION --github-target-enterprise ENTERPRISE

Remarque

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.

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

Espace réservé	Valeur
SOURCE	Nom de l’organisation source
DESTINATION	Nom que vous voulez que votre nouvelle organisation porte. Ne peut pas être partagé par une autre organisation sur votre plateforme de destination.
ENTREPRISE	Le slug de votre entreprise de destination, que vous pouvez identifier en consultant l’URL de votre compte d’entreprise, `https://github.com/enterprises/SLUG` ou `https://SLUG.ghe.com`.

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

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

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

Enfin, nous vous recommandons de vérifier la solidité de vos dépôts d’organisation et migrés.