Use GraphQL to migrate repositories from GitLab to GitHub Enterprise Cloud

Step 0: Get ready to use the GitHub GraphQL API

Para fazer consultas do GraphQL, você precisará escrever seus scripts ou usar um cliente HTTP como o Insomnia.

Para saber mais sobre como começar a usar a API do GraphQL do GitHub, incluindo como se autenticar, confira Realizar chamadas com o GraphQL.

Você enviará todas as consultas GraphQL para o destino da sua migração. Se você estiver migrando para o GitHub Enterprise Cloud com residência de dados, envie consultas para o ponto de extremidade do subdomínio da sua empresa do GHE.com.

Step 1: Get the ownerId for your migration destination

Como proprietário de uma organização no GitHub Enterprise Cloud, use a consulta GetOrgInfo para retornar a ownerId, também chamada de ID da organização, na organização da qual você deseja ser proprietário dos repositórios migrados. Você precisará da ownerId para identificar seu destino de migração.

Consulta GetOrgInfo

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

Variável da consulta	Descrição
login	O nome da sua organização.

Resposta GetOrgInfo

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

Neste exemplo, MDEyOk9yZ2FuaXphdGlvbjU2MTA= é a ID da organização ou ownerId, que usaremos na próxima etapa.

Step 2: Identify where you're migrating from

Você pode configurar uma origem de migração usando a consulta createMigrationSource. Você precisará fornecer a ownerId, ou a ID da organização, coletada da consulta GetOrgInfo.

Your migration source is your GitLab instance.

createMigrationSource mutation

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

Set url to the full URL of your GitLab instance, such as https://gitlab.com or https://gitlab.example.com. Make sure to use GITLAB for type.

Variável da consulta	Descrição
name	Um nome para a origem da migração. Esse nome se destina à sua referência, ou seja, você pode usar qualquer cadeia de caracteres.
ownerId	A ID da sua organização no GitHub Enterprise Cloud.

createMigrationSource response

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
        "name": "GitLab Source",
        "url": "https://gitlab.com",
        "type": "GITLAB"
      }
    }
  }
}

In this example, MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA is the migration source ID, which we'll use in a later step.

Step 3: Generate and host your migration archive

Migrations from GitLab are archive-based. Instead of connecting to your GitLab instance during the migration, GitHub Enterprise Importer imports a migration archive that you generate from your GitLab project. A GitLab archive is a single file that contains both the Git source and the repository's metadata.

Before you start the migration, you must:

1. Generate a migration archive for the GitLab project you want to migrate.
2. Host the archive at a URL that GitHub Enterprise Cloud can access.

You'll provide this URL as the gitArchiveUrl value in the next step.

Generating a migration archive

Use the GitLab project export API to export the project you want to migrate. The token you use must have the api scope and a role with permission to export the project. For more information, see Manage access for a migration from GitLab to GitHub.

In the following requests, set the GITLAB_PAT environment variable to the token you created in Manage access for a migration from GitLab to GitHub. Replace GITLAB-SERVER with the host of your GitLab instance, such as gitlab.com, and replace GROUP%2FPROJECT with the URL-encoded path of your project. For example, the project acme-group/my-project is encoded as acme-group%2Fmy-project. For nested subgroups, include the full path, such as parent-group%2Fsubgroup%2Fmy-project.

1. Schedule the export.

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

2. Check the status of the export. Repeat this request until export_status is finished.

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

3. Download the archive.

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

Hosting the archive

You must host the archive at a URL that GitHub Enterprise Cloud can access. You can either upload the archive to GitHub-owned blob storage or use an external blob storage provider. For information about external providers, see Configure blob storage.

To upload the archive to GitHub-owned blob storage, you'll need the database ID of your organization on GitHub Enterprise Cloud. Replace ORGANIZATION with the name of your organization to get this ID from the id field in the response.

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

Upload the archive with a POST request, replacing ORGANIZATION-ID with your organization's database ID. This request works for archives up to 100 MiB. For larger archives, use an external blob storage provider.

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"

The response includes a uri in the format gei://archive/GUID. Use this value as the gitArchiveUrl in the next step.

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

Step 4: Start your repository migration

Quando você inicia uma migração, um repositório individual e os dados complementares são migrados para um novo repositório do GitHub identificado por você.

Caso você deseje mover vários repositórios ao mesmo tempo da mesma organização de origem, coloque várias migrações na fila. É possível executar até cinco migrações de repositório ao mesmo tempo.

startRepositoryMigration mutation

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

Variável da consulta	Descrição
sourceId	A origem de migração id retornou da mutação createMigrationSource.
ownerId	A ID da sua organização no GitHub Enterprise Cloud.
repositoryName	Um nome de repositório exclusivo personalizado não usado atualmente por nenhum dos seus repositórios pertencentes à organização no GitHub Enterprise Cloud. Um problema de log de erros será criado neste repositório quando a migração for concluída ou tiver sido interrompida.
continueOnError	Configuração de migração que permite que a migração continue ao encontrar erros que não causam falha na migração. Deve ser true ou false. Recomendamos fortemente definir continueOnError como true, de modo que a migração continue, a menos que o Importer não possa mover a origem do Git ou o Importer tenha perdido a conexão e não possa se reconectar para concluir a migração.
githubPat	O personal access token da sua organização de destino no GitHub Enterprise Cloud.
accessToken	Os dados do personal access token da origem.
targetRepoVisibility	A visibilidade do novo repositório. Deve ser private, public ou internal. Se isso não estiver definido, seu repositório será migrado como privado.
gitArchiveUrl	A GitHub Enterprise Cloud-accessible URL to the migration archive you generated in the previous step. GitLab migrations use a single archive that contains both the Git source and metadata, so you don't need to provide a separate metadataArchiveUrl.
sourceRepositoryUrl	The URL of your source repository on GitLab, using the format https://GITLAB-SERVER/{group}/{project}. For nested subgroups, include the full path, such as https://GITLAB-SERVER/{parent-group}/{subgroup}/{project}. GitHub Enterprise Cloud does not connect to this URL during the migration; it's recorded for reference.

Because GitLab migrations are archive-based, GitHub Enterprise Cloud does not connect to GitLab during the migration. The accessToken variable is required by the mutation but isn't used, so you can set it to any placeholder value, such as not-used.

For personal access token requirements, see Manage access for a migration from GitLab to GitHub.

Na próxima etapa, você usará a ID de migração retornada da mutação startRepositoryMigration para verificar o status da migração.

Step 5: Check the status of your migration

Para detectar qualquer falha de migração e garantir que a migração esteja funcionando, verifique o status da migração usando a consulta getMigration. Você também pode verificar o status de várias migrações com getMigrations.

A consulta getMigration retornará com um status para informar se a migração é queued, in progress, failed ou completed. Em caso de falha na migração, o Importer fornecerá um motivo para a falha.

Consulta getMigration

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

Variável da consulta	Descrição
id	A id da migração que a mutação startRepositoryMigration retornou.

Step 6: Validate your migration and check the error log

Para concluir a migração, recomendamos que você verifique o problema "Log de Migração". Esse problema é criado no GitHub no repositório de destino.

Por fim, recomendamos que você revise os repositórios migrados para uma verificação de integridade.

Further reading

• Follow-up tasks