Migration de dépôts de GitHub.com vers GitHub Enterprise Cloud

À propos des migrations de dépôts 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.
Dans l’organisation source et de destination, vous devez être propriétaire d’organisation ou recevoir le rôle de migrateur. Pour plus d’informations, consultez « Gestion de l’accès pour une migration entre des produits GitHub ».

É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 le `ownerId` de la destination de votre migration

En tant que propriétaire de l’organisation dans GitHub Enterprise Cloud, utilisez la requête GetOrgInfo pour retourner l’ownerId, également appelé ID d’organisation, pour l’organisation dont vous souhaitez posséder les dépôts migrés. Vous aurez besoin de l’ownerId pour identifier votre destination de migration.

Requête `GetOrgInfo`

query(
  $login: String!
){
  organization (login: $login)
  {
    login
    id
    name
    databaseId
  }
}

Variable de requête	Description
`login`	Nom de votre organisation.

Réponse `GetOrgInfo`

{
  "data": {
    "organization": {
      "login": "Octo",
      "id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
      "name": "Octo-org",
      "databaseId": 5610
    }
  }
}

Dans cet exemple, MDEyOk9yZ2FuaXphdGlvbjU2MTA= est l’ID d’organisation ou le ownerId, que nous utiliserons à l’étape suivante.

Étape 2 : Identifier à partir d’où vous effectuez la migration

Vous pouvez configurer une source de migration à l’aide de la requête createMigrationSource. Vous devez fournir l’ownerId, ou l’ID d’organisation, collecté à partir de la requête GetOrgInfo.

La source de votre migration est une organisation sur GitHub.com.

Mutation `createMigrationSource`

mutation createMigrationSource($name: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: "https://github.com", ownerId: $ownerId, type: GITHUB_ARCHIVE}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

Remarque

Veillez à utiliser GITHUB_ARCHIVE pour type.

Variable de requête	Description
`name`	Nom pour votre source de migration. Ce nom est juste pour vous, donc vous pouvez utiliser n’importe quelle chaîne.
`ownerId`	ID d’organisation de votre organisation sur GitHub Enterprise Cloud.

Réponse `createMigrationSource`

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
        "name": "GitHub.com Source",
        "url": "https://github.com",
        "type": "GITHUB_SOURCE"
      }
    }
  }
}

Dans cet exemple, MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA est l’ID de la source de la migration, que nous allons utiliser à l’étape suivante.

Étape 3 : Démarrer la migration de votre dépôt

Lorsque vous démarrez une migration, un seul dépôt et ses données associées migrent vers un tout nouveau dépôt GitHub que vous identifiez.

Si vous souhaitez déplacer plusieurs dépôts à la fois de la même organisation source, vous pouvez mettre en file d’attente plusieurs migrations. Vous pouvez exécuter jusqu’à 5 migrations de dépôt en même temps.

Mutation `startRepositoryMigration`

mutation startRepositoryMigration (
  $sourceId: ID!,
  $ownerId: ID!,
  $sourceRepositoryUrl: URI!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

Variable de requête	Description
`sourceId`	`id` de votre source de migration retournée par la mutation `createMigrationSource`.
`ownerId`	ID d’organisation de votre organisation sur GitHub Enterprise Cloud.
`repositoryName`	Nom de dépôt unique personnalisé qui n’est actuellement utilisé par aucun de vos dépôts appartenant à l’organisation sur GitHub Enterprise Cloud. Un problème de journalisation des erreurs sera créé dans ce dépôt une fois votre migration terminée ou arrêtée.
`continueOnError`	Paramètre de migration qui permet à la migration de se poursuivre en cas d’erreurs qui n’entraînent pas l’échec de la migration. Doit être `true` ou `false`. Nous vous recommandons vivement de définir `continueOnError` sur `true` afin que votre migration continue, sauf si Importer ne peut pas déplacer la source Git ou que Importer a perdu la connexion et ne peut pas se reconnecter pour terminer la migration.
`githubPat`	personal access token pour votre organisation de destination sur GitHub Enterprise Cloud.
`accessToken`	personal access token pour votre source.
`targetRepoVisibility`	Visibilité du nouveau dépôt. Doit être `private`, `public` ou `internal`. Si elle n’est pas définie, votre dépôt est migré avec une visibilité privée.
`sourceRepositoryUrl`	URL de votre dépôt source, au format `https://github.com/{organization}/{repository}`.

Pour connaître les exigences relatives aux personal access token, veuillez consulter la section Gestion de l’accès pour une migration entre des produits GitHub.

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

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

Pour détecter les échecs de migration et vous assurer que votre migration fonctionne, vous pouvez vérifier l’état de votre migration en utilisant la requête getMigration. Vous pouvez également vérifier l’état de plusieurs migrations avec getMigrations.

La requête getMigration est retournée avec un état pour vous indiquer si la migration est queued, in progress, failed ou completed. Si votre migration a échoué, Importer fournit la raison de l’échec.

Requête `getMigration`

query (
  $id: ID!
){
  node( id: $id ) {
    ... on Migration {
      id
      sourceUrl
      migrationSource {
        name
      }
      state
      failureReason
    }
  }
}

Variable de requête	Description
`id`	`id` de votre migration que la mutation `startRepositoryMigration` a retourné.

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

Pour terminer votre migration, nous vous recommandons de consulter le problème « Journal de migration ». Ce problème est créé sur GitHub dans le dépôt de destination.

Capture d’écran d’un problème avec le titre « Journal de migration ». Le deuxième commentaire du problème contient les journaux d’une migration.

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

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

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 token qui peuvent accéder aux organisations source et de destination, puis définir les personal access token en tant que variables d’environnement.

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 ».
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.
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"
```
```
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 : 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.

Remarque

La génération d’un script génère un script PowerShell. Si vous utilisez le Terminal, vous devez générer le script avec l’extension de fichier .ps1 et installer PowerShell pour Mac ou Linux pour l’exécuter.

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

Génération d’un script de migration

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

Shell

gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME

gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME

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.

Espaces réservés

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

Arguments supplémentaires

Argument	Description
`--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`.
`--download-migration-logs`	Téléchargez le journal de migration pour chaque référentiel migré. Pour plus d'informations sur les journaux de migration, veuillez consulter la section Accès à vos journaux de migration pour GitHub Enterprise Importer.

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.

Étape 5 : 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.

Migrer plusieurs dépôts

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
```
```
./FILENAME
```
Si vous employez PowerShell, utilisez .\.
Shell
```
.\FILENAME
```
```
.\FILENAME
```

Migrer un seul dépôt

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

Shell

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME

Espaces réservés

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
CURRENT-NAME	Nom du dépôt que vous souhaitez migrer
DESTINATION	Nom de l’organisation de destination
NEW-NAME	Nom que vous souhaitez donner au dépôt migré

Arguments supplémentaires

Argument	Description
`--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`.
`--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-repo-visibility TARGET-VISIBILITY`	Les dépôts sont migrés avec une visibilité privée par défaut. Pour définir la visibilité, vous pouvez ajouter l’indicateur `--target-repo-visibility`, spécifier `private`, `public`, ou `internal`. Si vous effectuez une migration vers un entreprise avec utilisateurs managés, les référentiels publics ne sont pas disponibles.

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

Shell

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

gh gei 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é.

Migration de dépôts de GitHub.com vers GitHub Enterprise Cloud

Tool navigation

Dans cet article

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

Prérequis

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

Étape 1 : Obtenir le `ownerId` de la destination de votre migration

Requête `GetOrgInfo`

Réponse `GetOrgInfo`

Étape 2 : Identifier à partir d’où vous effectuez la migration

Mutation `createMigrationSource`

Réponse `createMigrationSource`

Étape 3 : Démarrer la migration de votre dépôt

Mutation `startRepositoryMigration`

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

Requête `getMigration`

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

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

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

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

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

Génération d’un script de migration

Espaces réservés

Arguments supplémentaires

Examen du script de migration

Étape 5 : Migrer des dépôts

Migrer plusieurs dépôts

Migrer un seul dépôt

Espaces réservés

Arguments supplémentaires

Abandon de la migration

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