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

Si vous choisissez d’utiliser l’API, vous devrez écrire vos propres scripts ou utiliser un client HTTP comme Insomnia. Pour bien démarrer avec les API de GitHub, consultez « Prise en main de l’API REST » et « Formation d’appels avec GraphQL ».

Pour migrer vos dépôts de GitHub Enterprise Server vers GitHub Enterprise Cloud avec les API, vous devez :

1. Créer un personal access token pour les organisations source et de destination
2. Récupérer le ownerId de l’organisation de destination sur GitHub Enterprise Cloud
3. Configurer une source de migration via l’API GraphQL de GitHub pour identifier l’emplacement d’origine de la migration
4. Pour chaque dépôt que vous souhaitez migrer, répétez ces étapes.
   • Utiliser l’API REST sur votre instance GitHub Enterprise Server pour générer des archives de migration pour votre dépôt
   • Charger vos archives de migration dans un emplacement accessible à GitHub
   • Démarrez votre migration à l’aide de l’API GraphQL pour votre destination de migration, en passant vos URL d’archivage
   • Vérifier l’état de votre migration via l’API GraphQL
   • Valider votre migration et consulter le journal des erreurs

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

Étape 1. Créer votre personal access token

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

Étape 2 : Obtenir le ownerId pour l’organisation de destination

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

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 3 : Configurer le stockage d’objets blob

De nombreuses instances GitHub Enterprise Server se trouvant derrière des pare-feux, pour GitHub Enterprise Server version 3.8 ou ultérieure, nous utilisons le stockage d’objets blob comme emplacement intermédiaire pour stocker les données auxquelles GitHub peut accéder.

Vous devez d’abord configurer le stockage d’objets blob avec un fournisseur de cloud pris en charge, puis configurer vos paramètres dans la Management Console de votre instance GitHub Enterprise Server.

Configuration du stockage d’objets blob avec un fournisseur de cloud pris en charge

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

• Amazon Web Services (AWS) S3
• Stockage Blob Azure

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.

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 «  Administrateur de site », 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, vous devrez peut-être toujours mettre à jour la configuration de votre compte de stockage cloud pour utiliser 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 les 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.

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

Autorisation de l’accès 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 les produits GitHub ».

Étape 4 : Configurer une source de migration dans GitHub Enterprise Cloud

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 votre organisation sur GitHub Enterprise Server.

Mutation createMigrationSource

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

Réponse createMigrationSource

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ",
        "name": "GHES Source",
        "url": "https://my-ghes-hostname.com",
        "type": "GITHUB_ARCHIVE"
      }
    }
  }
}

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

Étape 5 : Générer des archives de migration sur votre instance GitHub Enterprise Server

Vous allez utiliser l’API REST pour démarrer deux « migrations » dans GitHub Enterprise Server : une pour générer une archive de la source Git de votre dépôt et une pour générer une archive des métadonnées (comme les problèmes et les demandes de tirage) de votre dépôt.

Pour générer l’archive de la source Git, envoyez une demande POST à https://HOSTNAME/api/v3/orgs/ORGANIZATION/migrations, en remplaçant HOSTNAME par le nom d’hôte de votre instance GitHub Enterprise Server et ORGANIZATION par l’identifiant de connexion de votre organisation.

Dans le corps, spécifiez le dépôt unique que vous souhaitez migrer. Votre demande doit ressembler à ceci :

POST /api/v3/orgs/acme-corp/migrations HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Content-Type: application/json
Host: github.acmecorp.net

{
  "repositories": ["repository_to_migrate"],
  "exclude_metadata": true
}

Pour générer une archive de vos métadonnées, envoyez une demande similaire à la même URL avec le corps suivant :

{
  "repositories": ["repository_to_migrate"],
  "exclude_git_data": true,
  "exclude_releases": false,
  "exclude_owner_projects": true
}

Chacun de ces appels d’API retourne une réponse JSON comprenant l’ID de la migration que vous avez démarrée.

HTTP/1.1 201 Created

{
  "id": 123,
  // ...
}

Pour plus d’informations, consultez « Démarrer une migration d’organisation .»

En fonction de la quantité de données, la génération des archives peut prendre un certain temps. Vous pouvez vérifier régulièrement l’état des deux migrations avec l’API « Obtenir l’état d’une migration d’organisation », jusqu’à ce que l’état (state) de la migration passe à exported.

GET /api/v3/orgs/acme-corp/migrations/123 HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "state": "exported",
  // ...
}

Pour plus d’informations, consultez « Obtenir l’état d’une migration d’organisation ».

Quand l’état (state) d’une migration passe à exported, vous pouvez récupérer l’URL de la migration à l’aide de l’API « Télécharger une archive de migration d’organisation ».

GET /api/v3/orgs/acme-corp/migrations/123/archive HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 302 Found
Location: https://media.github.acmecorp.net/migrations/123/archive/cca2ebe9-7403-4ffa-9b6a-4c9e16c94410?token=AAAAABEWE7JP4H2HACKEGMTDOYRC6

L’API retourne une réponse 302 Found avec un en-tête Location qui redirige vers l’URL où se trouve l’archive téléchargeable. Téléchargez les deux fichiers : un pour la source Git et un pour les métadonnées.

Pour plus d’informations, consultez « Télécharger une archive de migration d’organisation .»

Une fois les deux migrations terminées et les archives téléchargées, vous pouvez passer à l’étape suivante.

Étape 6 : Charger vos archives de migration

Pour importer vos données dans GitHub Enterprise Cloud, vous devez passer les deux archives de chaque dépôt (source Git et métadonnées) de votre ordinateur à GitHub, à l’aide de notre API GraphQL.

Si vous utilisez GitHub Enterprise Server 3.7 ou antérieur, vous devez d’abord générer des URL pour les archives accessibles à GitHub. La plupart des clients choisissent de charger les archives sur le service de stockage d’objets blob d’un fournisseur de cloud, comme Amazon S3 ou Stockage Blob Azure, puis de générer une URL à courte durée de vie pour chaque archive.

Si vous utilisez GitHub Enterprise Server 3.8 ou ultérieur, votre instance charge les archives et génère les URL pour vous. L’en-tête Location de l’étape précédente retourne l’URL à courte durée de vie.

Vous devrez peut-être établir une liste d’autorisation des plages d’adresses IP de GitHub. Pour plus d’informations, consultez « Gestion de l'accès pour une migration entre les produits GitHub ».

Étape 7 : 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!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $gitArchiveUrl: String!,
  $metadataArchiveUrl: String!,
  $sourceRepositoryUrl: URI!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility
    gitArchiveUrl: $gitArchiveUrl,
    metadataArchiveUrl: $metadataArchiveUrl,
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

Pour connaître les exigences en termes de personal access token, consultez « Gestion de l'accès pour une migration entre les 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 8 : 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
    }
  }
}

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

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