Utiliser GraphQL pour migrer des référentiels de GitLab vers GitHub Enterprise Cloud

Remarque

Vous pouvez également utiliser GL2GH extension of the GitHub CLI pour effectuer votre migration. Consultez « Comprendre les migrations de GitLab vers GitHub ».

Étape 0 : Préparer l’utilisation de l’API GitHub GraphQL

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 Création 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.

Votre source de migration est votre instance GitLab.

Mutation `createMigrationSource`

mutation createMigrationSource($name: String!, $url: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: $url, ownerId: $ownerId, type: GITLAB}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

Définissez url sur l’URL complète de votre instance GitLab, par https://gitlab.com exemple ou https://gitlab.example.com. Veillez à utiliser GITLAB 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": "GitLab Source",
        "url": "https://gitlab.com",
        "type": "GITLAB"
      }
    }
  }
}

Dans cet exemple, MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA est l’ID de la source de la migration. Nous l’utiliserons dans une étape ultérieure.

Étape 3 : Générer et héberger votre archive de migration

Les migrations de GitLab sont basées sur des archives. Au lieu de vous connecter à votre instance GitLab pendant la migration, GitHub Enterprise Importer importe une archive de migration que vous générez à partir de votre projet GitLab. Une archive GitLab est un fichier unique qui contient à la fois la source Git et les métadonnées du référentiel.

Avant de commencer la migration, vous devez :

Générez une archive de migration pour le projet GitLab que vous souhaitez migrer.
Hébergez l’archive à l’adresse d’une URL qui GitHub Enterprise Cloud peut y accéder.

Vous fournirez cette URL comme gitArchiveUrl valeur à l’étape suivante.

Génération d’une archive de migration

Utilisez l’API d’exportation de projet GitLab pour exporter le projet que vous souhaitez migrer. Le jeton que vous utilisez doit avoir l’étendue api et un rôle autorisé à exporter le projet. Pour plus d’informations, consultez « Gérer l’accès à une migration de GitLab vers GitHub ».

Dans les requêtes suivantes, définissez la GITLAB_PAT variable d’environnement sur le jeton que vous avez créé dans Gérer l’accès à une migration de GitLab vers GitHub. Remplacez GITLAB-SERVER par l’hôte de votre instance GitLab, par gitlab.comexemple, et remplacez GROUP%2FPROJECT par le chemin codé par URL de votre projet. Par exemple, le projet acme-group/my-project est encodé en tant que acme-group%2Fmy-project. Pour les sous-groupes imbriqués, incluez le chemin d’accès complet, par parent-group%2Fsubgroup%2Fmy-projectexemple .

Planifiez l’exportation.

curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"

Vérifiez l’état de l’exportation. Répétez cette requête jusqu’à ce qu’elle export_status soit finished.
```
curl --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"
```

Téléchargez l’archive.

curl --location \
  --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  --output archive.tar.gz \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export/download"

Hébergement de l’archive

Vous devez héberger l’archive à une URL qui GitHub Enterprise Cloud peut y accéder. Vous pouvez charger l’archive vers GitHub-owned blob storage ou utiliser un fournisseur de stockage d’objets blob externe. Pour plus d’informations sur les fournisseurs externes, consultez Configurer le stockage d’objets blob.

Pour charger l’archive GitHub-owned blob storage, vous aurez besoin de l’ID de base de données de votre organisation sur GitHub Enterprise Cloud. Remplacez ORGANIZATION par le nom de votre organisation pour obtenir cet ID à partir du id champ dans la réponse.

curl --header "Authorization: Bearer YOUR-TOKEN" \
  "https://api.github.com/orgs/ORGANIZATION"

Remarque

Si vous effectuez une migration vers GHE.com, remplacez https://api.github.com par l’URL de l’API de base pour le sous-domaine de votre entreprise, par https://api.octocorp.ghe.comexemple .

Chargez l’archive avec une POST demande, en ORGANIZATION-ID remplaçant par l’ID de base de données de votre organisation. Cette demande fonctionne pour les archives jusqu’à 100 Mio. Pour les archives plus volumineuses, utilisez un fournisseur de stockage d’objets blob externe.

curl --request POST \
  --header "Authorization: Bearer YOUR-TOKEN" \
  --header "Content-Type: application/octet-stream" \
  --data-binary @archive.tar.gz \
  "https://uploads.github.com/organizations/ORGANIZATION-ID/gei/archive?name=archive.tar.gz"

Remarque

Si vous effectuez une migration vers GHE.com, remplacez uploads.github.com par l’hôte de chargement pour le sous-domaine de votre entreprise, par uploads.octocorp.ghe.comexemple .

La réponse inclut un uri format gei://archive/GUID. Utilisez cette valeur comme dans gitArchiveUrl l’étape suivante.

{
  "guid": "ff7b1a25-aa10-41a9-8e42-f170304b1c0d",
  "node_id": "MA_kgDaACRmZjdiMWEyNS1hYTEwLTQxYTktOGU0Mi1mMTcwMzA0YjFjMGQ",
  "name": "archive.tar.gz",
  "size": 7103,
  "uri": "gei://archive/ff7b1a25-aa10-41a9-8e42-f170304b1c0d",
  "created_at": "2024-11-13T12:35:45.761-08:00"
}

Étape 4 : 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!,
  $gitArchiveUrl: String!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility,
    gitArchiveUrl: $gitArchiveUrl,
    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.

| gitArchiveUrl | GitHub Enterprise CloudURL accessible à l’archive de migration que vous avez générée à l’étape précédente. Les migrations GitLab utilisent une archive unique qui contient à la fois la source Git et les métadonnées. Vous n’avez donc pas besoin de fournir une archive distincte metadataArchiveUrl.

| sourceRepositoryUrl | URL de votre référentiel source sur GitLab à l’aide du format https://GITLAB-SERVER/{group}/{project}. Pour les sous-groupes imbriqués, incluez le chemin d’accès complet, par https://GITLAB-SERVER/{parent-group}/{subgroup}/{project}exemple . GitHub Enterprise Cloud ne se connecte pas à cette URL pendant la migration ; il est enregistré pour référence.

Étant donné que les migrations GitLab sont basées sur des archives, GitHub Enterprise Cloud ne se connectent pas à GitLab pendant la migration. La accessToken variable est requise par la mutation, mais n’est pas utilisée. Vous pouvez donc la définir sur n’importe quelle valeur d’espace réservé, telle que not-used.

Pour la configuration requise pour personal access token, consultez Gérer l’accès à une migration de GitLab vers 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 5 : 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 6 : 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é.

Lectures complémentaires

Tâches de suivi

Utiliser GraphQL pour migrer des référentiels de GitLab vers GitHub Enterprise Cloud

Dans cet article