Use GraphQL to migrate repositories from GitLab to GitHub Enterprise Cloud

Примечание.

You can also use GL2GH extension of the GitHub CLI to perform your migration. See Understand migrations from GitLab to GitHub.

Step 0: Get ready to use the GitHub GraphQL API

Чтобы сделать запросы GraphQL, вам потребуется написать собственные скрипты или использовать HTTP-клиент, такой как бессонница.

Дополнительные сведения о начале работы с API GraphQL GitHub GraphQL, включая проверку подлинности, см. в статье Формирование вызовов с помощью GraphQL.

Все запросы GraphQL отправляются в место назначения миграции. Если вы переносите данные GitHub Enterprise Cloud с размещением данных, обязательно отправьте запросы в конечную точку поддомена вашего предприятия GHE.com.

Step 1: Get the `ownerId` for your migration destination

В качестве владелец организации в GitHub Enterprise Cloudиспользуйте GetOrgInfo запрос для возврата ownerIdидентификатора организации, которая также называется идентификатором организации, для которой требуется принадлежать перенесенные репозитории. Вам потребуется ownerId определить назначение миграции.

`GetOrgInfo` запрос

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

Переменная запроса	Description
`login`	Имя вашей организации.

`GetOrgInfo` ответ

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

В этом примере MDEyOk9yZ2FuaXphdGlvbjU2MTA= — это идентификатор организации или ownerIdидентификатор организации, который мы будем использовать на следующем шаге.

Step 2: Identify where you're migrating from

Вы можете настроить источник миграции с помощью createMigrationSource запроса. Вам потребуется указать ownerIdидентификатор организации, собранный 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.

Переменная запроса	Description
`name`	Имя источника миграции. Это имя для собственной ссылки, поэтому можно использовать любую строку.
`ownerId`	Идентификатор организации в 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:

Generate a migration archive for the GitLab project you want to migrate.
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.

Schedule the export.

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

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"

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"

Примечание.

If you're migrating to GHE.com, replace https://api.github.com with the base API URL for your enterprise's subdomain, such as https://api.octocorp.ghe.com.

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"

Примечание.

If you're migrating to GHE.com, replace uploads.github.com with the uploads host for your enterprise's subdomain, such as uploads.octocorp.ghe.com.

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

При запуске миграции один репозиторий и его сопутствующие данные переносятся в новый репозиторий GitHub, который вы определяете.

Если вы хотите одновременно переместить несколько репозиториев из одной исходной организации, можно ставить в очередь несколько миграций. Одновременно можно выполнять до 5 миграций репозитория.

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

Переменная запроса	Description
`sourceId`	Источник миграции `id` вернулся из мутации `createMigrationSource` .
`ownerId`	Идентификатор организации в GitHub Enterprise Cloud.
`repositoryName`	Пользовательское уникальное имя репозитория, которое в настоящее время не используется ни одной из репозиториев, принадлежащих организации, на GitHub Enterprise Cloud. Проблема с ведением журнала ошибок будет создана в этом репозитории при завершении или остановке миграции.
`continueOnError`	Параметр миграции, позволяющий продолжить миграцию при возникновении ошибок, которые не вызывают сбой миграции. Должно быть `true` или `false`. Настоятельно рекомендуется задать значение `continueOnError` `true` , чтобы миграция продолжалась, если только Importer не может переместить источник Git или Importer потерял соединение и не сможет повторно подключиться к миграции.
`githubPat`	personal access token для целевой организации на GitHub Enterprise Cloud.
`accessToken`	personal access token для источника.
`targetRepoVisibility`	Видимость нового репозитория. Должно быть `private`, `public` или `internal`. Если этот параметр не задан, репозиторий переносится как закрытый.
`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.

На следующем шаге вы будете использовать идентификатор миграции, возвращенный из startRepositoryMigration изменения, чтобы проверить состояние миграции.

Step 5: Check the status of your migration

Чтобы обнаружить любые сбои миграции и убедиться, что миграция работает, можно проверить состояние миграции с помощью getMigration запроса. Вы также можете проверить состояние нескольких миграций.getMigrations

Запрос getMigration возвращается с состоянием, чтобы сообщить, является queuedли миграция , in progress``failedили completed. Если миграция завершилась сбоем, Importer предоставит причину сбоя.

`getMigration` запрос

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

Переменная запроса	Description
`id`	Миграция`id`, возвращаемая мутацией`startRepositoryMigration`.

Step 6: Validate your migration and check the error log

Чтобы завершить миграцию, рекомендуется проверить проблему журнала миграции. Эта проблема создается на GitHub в целевом репозитории.

Снимок экрана: проблема с заголовком "Журнал миграции". Второй комментарий в этой проблеме включает журналы для миграции.

Наконец, рекомендуется просмотреть перенесенные репозитории для проверки звука.

Use GraphQL to migrate repositories from GitLab to GitHub Enterprise Cloud

В этой статье

Step 0: Get ready to use the GitHub GraphQL API

Step 1: Get the `ownerId` for your migration destination

`GetOrgInfo` запрос

`GetOrgInfo` ответ

Step 2: Identify where you're migrating from

`createMigrationSource` mutation

`createMigrationSource` response

Step 3: Generate and host your migration archive

Generating a migration archive

Hosting the archive

Step 4: Start your repository migration

`startRepositoryMigration` mutation

Step 5: Check the status of your migration

`getMigration` запрос

Step 6: Validate your migration and check the error log

Further reading