GraphQL を使用して GitLab から GitHub Enterprise Cloud にリポジトリを移行する

メモ

GL2GH extension of the GitHub CLIを使用して移行を実行することもできます。「GitLab から GitHub への移行について」を参照してください。

手順 0: GitHub GraphQL API を使用する準備をする

GraphQL クエリを作成するには、独自のスクリプトを記述するか、Insomnia などの HTTP クライアントを使う必要があります。

認証方法など、GitHub GraphQL API の概要については、「GraphQLでの呼び出しの作成」を参照してください。

すべての GraphQL クエリを、移行先に送信します。データ所在地付き GitHub Enterprise Cloud に移行する場合は、GHE.com のエンタープライズのサブドメインのエンドポイントにクエリを送信してください。

手順 1: 移行先の`ownerId` を取得する

GitHub Enterprise Cloud の Organization 所有者として、GetOrgInfo クエリを使って、移行されたリポジトリを所有する Organization の ownerId (Organization ID とも呼ばれます) を取得します。移行先を識別するには、ownerId が必要です。

`GetOrgInfo` クエリ

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

クエリ変数	説明
`login`	Organization の名前。

`GetOrgInfo` の応答

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

この例では、MDEyOk9yZ2FuaXphdGlvbjU2MTA= が Organization ID つまり ownerId であり、次のステップでそれを使います。

手順 2: 移行元の場所を特定する

createMigrationSource クエリを使って、移行元を設定できます。 GetOrgInfo クエリで収集した ownerId つまり Organization ID を指定する必要があります。

移行ソースは GitLab インスタンスです。

`createMigrationSource` 変異

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

url https://gitlab.comやhttps://gitlab.example.comなど、GitLab インスタンスの完全な URL に設定します。 GITLAB には type を使用するようにしてください。

クエリ変数	説明
`name`	移行元の名前。この名前は自分の参照用であるため、任意の文字列を使用できます。
`ownerId`	GitHub Enterprise Cloud での Organization の Organization ID。

`createMigrationSource` に対する応答

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

この例では、MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA が移行元 ID です。これを後の手順で使用します。

手順 3: 移行アーカイブを生成してホストする

GitLab からの移行はアーカイブベースです。移行中に GitLab インスタンスに接続する代わりに、 GitHub Enterprise Importer は GitLab プロジェクトから生成した移行アーカイブをインポートします。 GitLab アーカイブは、Git ソースとリポジトリのメタデータの両方を含む 1 つのファイルです。

移行を開始する前に、次の作業を行う必要があります。

移行する GitLab プロジェクトの移行アーカイブを生成します。
GitHub Enterprise Cloudがアクセスできる URL でアーカイブをホストします。

この URL は、次の手順で gitArchiveUrl 値として指定します。

移行アーカイブの生成

GitLab プロジェクトエクスポート API を使用して、移行するプロジェクトをエクスポートします。使用するトークンには、 api スコープと、プロジェクトをエクスポートするアクセス許可を持つロールが必要です。詳細については、「GitLab から GitHub への移行のアクセスを管理する」を参照してください。

次の要求で、 GITLAB_PAT 環境変数を GitLab から GitHub への移行のアクセスを管理するで作成したトークンに設定します。 GITLAB-SERVERを gitLab インスタンスのホスト (gitlab.com など) に置き換え、GROUP%2FPROJECTをプロジェクトの URL でエンコードされたパスに置き換えます。たとえば、プロジェクト acme-group/my-project は acme-group%2Fmy-projectとしてエンコードされます。入れ子になったサブグループの場合は、 parent-group%2Fsubgroup%2Fmy-projectなどの完全なパスを含めます。

エクスポートをスケジュールします。

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

エクスポートの状態を確認します。 export_statusがfinishedされるまで、この要求を繰り返します。
```
curl --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"
```

アーカイブをダウンロードします。

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

アーカイブのホスト

GitHub Enterprise Cloudアクセスできる URL でアーカイブをホストする必要があります。アーカイブを GitHub-owned blob storage にアップロードすることも、外部 BLOB ストレージプロバイダーを使用することもできます。外部プロバイダーの詳細については、 BLOB ストレージを構成するを参照してください。

アーカイブを GitHub-owned blob storageにアップロードするには、 GitHub Enterprise Cloudに組織のデータベース ID が必要です。 ORGANIZATIONを組織の名前に置き換えて、応答の id フィールドからこの ID を取得します。

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

メモ

GHE.comに移行する場合は、https://api.github.comを企業のサブドメインのベース API URL (https://api.octocorp.ghe.com など) に置き換えます。

アーカイブを POST 要求でアップロードし、 ORGANIZATION-ID を組織のデータベース ID に置き換えます。この要求は、最大 100 MiB のアーカイブに対して機能します。大規模なアーカイブの場合は、外部 BLOB ストレージプロバイダーを使用します。

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"

メモ

GHE.comに移行する場合は、uploads.github.comを企業のサブドメインのアップロードホスト (uploads.octocorp.ghe.com など) に置き換えます。

応答には、gei://archive/GUID形式のuriが含まれます。この値は、次の手順の gitArchiveUrl として使用します。

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

手順 4: リポジトリの移行を開始する

移行を始める、1 つのリポジトリとそれに付随するデータが、ユーザーが指定した新しい GitHub リポジトリに移行されます。

同じ移行元 Organization から複数のリポジトリを一度に移動したい場合は、複数の移行をキューに登録できます。同時に最大 5 つのリポジトリの移行を実行できます。

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

クエリ変数	説明
`sourceId`	`createMigrationSource` ミューテーションから返された移行元の `id`。
`ownerId`	GitHub Enterprise Cloud での Organization の Organization ID。
`repositoryName`	GitHub Enterprise Cloud 上で Organization が所有するどのリポジトリでも現在使われていない一意のカスタムリポジトリ名。移行が完了または停止すると、このリポジトリにエラーログ issue が作成されます。
`continueOnError`	移行の失敗を引き起こさないエラーが発生したときに移行を続行できるようにする移行設定。 `true` または `false` である必要があります。 Importer が Git ソースを移動できない場合、または Importer が接続を失い、移行を完了するために再接続できない場合を除き、移行が続けられるように、`continueOnError` を `true` に設定することを強くお勧めします。
`githubPat`	personal access token 上の移行先 Organization の GitHub Enterprise Cloud。
`accessToken`	移行元の personal access token。
`targetRepoVisibility`	新しいリポジトリの可視性。 `private`、`public`、または `internal` にする必要があります。設定されていない場合、リポジトリはプライベートとして移行されます。

| gitArchiveUrl |前の手順で生成した移行アーカイブへの GitHub Enterprise Cloudアクセス可能な URL。 GitLab 移行では、Git ソースとメタデータの両方を含む 1 つのアーカイブが使用されるため、別の metadataArchiveUrlを指定する必要はありません。

| sourceRepositoryUrl | https://GITLAB-SERVER/{group}/{project}形式を使用した GitLab 上のソースリポジトリの URL。入れ子になったサブグループの場合は、 https://GITLAB-SERVER/{parent-group}/{subgroup}/{project}などの完全なパスを含めます。 GitHub Enterprise Cloud は、移行中にこの URL に接続しません。参照用に記録されます。

GitLab の移行はアーカイブベースであるため、移行中 GitHub Enterprise Cloud は GitLab に接続しません。 accessToken変数は変更に必要ですが、使用されないため、not-usedなどの任意のプレースホルダー値に設定できます。

personal access token要件については、GitLab から GitHub への移行のアクセスを管理するを参照してください。

次のステップでは、startRepositoryMigration ミューテーションから返された移行 ID を使って、移行の状態を調べます。

手順 5: 移行の状態を確認する

移行エラーを検出し、移行が行われていることを確認するには、getMigration クエリを使って移行の状態を調査できます。また、getMigrations を使うと、複数の移行の状態を調べることもできます。

getMigration クエリから返される状態を調べて、移行が queued、in progress、failed、または completed であるかどうかを確認できます。移行が失敗した場合、Importer によってエラーの原因が示されます。

`getMigration` クエリ

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

クエリ変数	説明
`id`	`startRepositoryMigration` ミューテーションが返した移行の `id`。

手順 6: 移行を検証し、エラーログを確認する

移行を完了するには、"移行ログ" の issue を確認することをお勧めします。この issue は、移行先リポジトリの GitHub に作成されます。

"移行ログ" というタイトルの issue のスクリーンショット。 issue の 2 番目のコメントに、移行に関するログが含まれます。

最後に、移行したリポジトリで健全性チェックを確認することをお勧めします。

詳細については、次を参照してください。

フォローアップタスク

GraphQL を使用して GitLab から GitHub Enterprise Cloud にリポジトリを移行する

この記事で