GitHub Enterprise Server から GitHub Enterprise Cloud へのリポジトリの移行

API を使用することを選んだ場合は、独自のスクリプトを記述するか、Insomnia などの HTTP クライアントを使用する必要があります。 GitHub の API の概要については、「REST API を使用した作業の開始」と「GraphQLでの呼び出しの作成」を参照してください。

API を使用してリポジトリを GitHub Enterprise Server から GitHub Enterprise Cloud に移行するには、次のようにします。

1. 移行元と移行先の両方の Organization に対して personal access token を作成します
2. GitHub Enterprise Cloud で移行先 Organization の ownerId をフェッチします
3. GitHub の GraphQL API を使用して移行元を設定し、どこから移行するかを特定します
4. 移行するリポジトリごとに、次の手順を繰り返します。
   • お使いの GitHub Enterprise Server インスタンス で、REST API を使用してリポジトリの移行アーカイブを生成します
   • GitHub からアクセスできる場所に移行アーカイブをアップロードします
   • GitHub の GraphQL API を使用して移行を開始し、アーカイブの URL を渡します
   • GraphQL API を使用して移行の状態を確認します
   • 移行を検証し、エラー ログを確認します

GitHub CLI の使い方を確認するには、ページの上部にあるツール スイッチャーを使います。

手順 1. personal access token を作成する

1. GitHub Enterprise Cloud 上の移行先 Organization に対して認証を行う personal access token (classic) を作成して記録し、トークンがすべての要件を満たしていることを確認します。 詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
2. 移行元 Organization に対して認証を行う personal access token を作成して記録し、このトークンも同じ要件をすべて満たしていることを確認します。

手順 2: 移行先 Organization の 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 であり、次のステップでそれを使います。

手順 3: BLOB ストレージを設定する

多くの GitHub Enterprise Server インスタンスはファイアウォールの内側にあるため、GitHub Enterprise Server バージョン 3.8 以降では、GitHub がアクセスできるデータを格納するための中間的な場所として、BLOB ストレージを使用します。

最初に、サポートされているクラウド プロバイダーで BLOB ストレージを設定してから、お使いの GitHub Enterprise Server インスタンス の [Management Console] で設定を構成する必要があります。

サポートされているクラウド プロバイダーを使用した BLOB ストレージの設定

GitHub CLI は、次の BLOB ストレージ プロバイダーをサポートしています。

• アマゾン ウェブ サービス (AWS) S3
• Azure Blob Storage

AWS S3 ストレージ バケットの設定

AWS で、S3 バケットを設定します。 詳しくは、AWS のドキュメント「バケットの作成」をご覧ください。

次のアクセス許可を持つ AWS アクセス キーと秘密鍵も必要です。

{
    "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/*"
            ]
        }
    ]
}

Azure Blob Storage アカウントの設定

Azure でストレージ アカウントを作成し、接続文字列を記録しておきます。 詳しくは、Microsoft Docs の「ストレージ アカウント アクセス キーを管理する」をご覧ください。

お使いの GitHub Enterprise Server インスタンス の [Management Console] での BLOB ストレージの構成

AWS S3 ストレージ バケットまたは Azure Blob Storage ストレージ アカウントを設定したら、お使いの GitHub Enterprise Server インスタンス の [Management Console] で BLOB ストレージを構成します。 [Management Console] について詳しくは、「管理コンソールからのインスタンスの管理」をご覧ください。

1. GitHub Enterprise Server の管理アカウントから、任意のページの右上隅にある をクリックします。

2. [サイト管理者] ページが表示されていない場合は、左上隅の [サイト管理者] をクリックします。1. [ サイト管理者] サイドバーで [Management Console] をクリックします。

3. [Management Console] にログインします。

4. 上部のナビゲーション バーで [設定] をクリックします。

5. [移行] で、 [GitHub の移行を有効にする] をクリックします。

6. GitHub Actions に構成したストレージの設定をインポートする必要がある場合は、 [Actions からストレージの設定をコピーする] をオンにします。 詳しくは、「Azure Blob ストレージで GitHub Actions を有効化する」と「Amazon S3 ストレージで GitHub Actions を有効化する」をご覧ください。

   注: ストレージ設定をコピーした後も、GitHub Enterprise Importer で動作するようにクラウド ストレージ アカウントの構成を更新する必要がある場合があります。 特に、GitHub の IP アドレスを許可リストに載せる必要があります。 詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。

7. GitHub Actions からストレージの設定をインポートしない場合は、 [Azure Blob Storage] または [Amazon S3] を選び、必要な詳細を入力します。

   注: Amazon S3 を使用する場合は、バケットが配置されている AWS リージョンの標準エンドポイントに 「AWS サービス URL」 を設定する必要があります。 たとえば、バケットがeu-west-1リージョンにある場合、「AWS サービス URL」 は https://s3.eu-west-1.amazonaws.com です。 GitHub Enterprise Server インスタンスのネットワークでは、このホストへのアクセスを許可する必要があります。 ゲートウェイ エンドポイントはサポートされていません。次にbucket.vpce-0e25b8cdd720f900e-argc85vg.s3.eu-west-1.vpce.amazonaws.comのような例を示します。 ゲートウェイエンドポイントの詳細については、AWS ドキュメントの Amazon S3 ゲートウェイエンドポイントを参照してください。

8. [ストレージの設定をテストする] をクリックします。

9. Save settings をクリックします。

手順 4: GitHub Enterprise Cloud で移行元を設定する

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

移行元は、GitHub Enterprise Server 上の Organization です。

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

クエリ変数	説明
name	移行元の名前。 この名前は自分の参照用であるため、任意の文字列を使用できます。
ownerId	GitHub Enterprise Cloud での Organization の Organization ID。
url	お使いの GitHub Enterprise Server インスタンス の URL。 この URL は、GitHub Enterprise Cloud からアクセスできる必要はありません。

createMigrationSource の応答

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

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

手順 5: お使いの GitHub Enterprise Server インスタンス で移行アーカイブを生成する

REST API を使用して、GitHub Enterprise Server で 2 つの "移行" を開始します。1 つはリポジトリの Git ソースのアーカイブを生成し、もう 1 つはリポジトリのメタデータ (issue や pull request など) のアーカイブを生成します。

Git ソース アーカイブを生成するには、https://HOSTNAME/api/v3/orgs/ORGANIZATION/migrations に対して POST 要求を行います。HOSTNAME は お使いの GitHub Enterprise Server インスタンス のホスト名に、ORGANIZATION は Organization のログインに置き換えます。

本文で、移行する 1 つのリポジトリを指定します。 要求はこのようになります。

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
}

メタデータ アーカイブを生成するには、次の本文を使用して同じ URL に同様の要求を送信します。

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

これら 2 つの API 呼び出しのそれぞれで、開始した移行の ID を含む JSON 応答が返されます。

HTTP/1.1 201 Created

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

詳細については、「Organization の移行を開始する」を参照してください。

データの量によっては、アーカイブの生成に時間がかかる場合があります。 "Organization の移行状態を取得する" API を使用して、移行の state が exported に変わるまで、2 つの移行の状態を定期的に確認できます。

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",
  // ...
}

詳細については、「Organization の移行状態を取得する」を参照してください。

移行の state が exported に推移したら、"Organization 移行アーカイブのダウンロード" API を使用して移行の URL をフェッチできます。

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

この API を使用すると、ダウンロード可能なアーカイブが配置された URL にリダイレクトする Location ヘッダーを含む 302 Found 応答が返されます。 2 つのファイルをダウンロードします。1 つは Git ソース、もう 1 つはメタデータのファイルです。

詳細については、「Organization の移行アーカイブをダウンロードする」を参照してください。

両方の移行が完了し、アーカイブをダウンロードしたら、次の手順に進むことができます。

手順 6: 移行アーカイブをアップロードする

GitHub Enterprise Cloud にデータをインポートするには、GraphQL API を使用して、自分のマシンから GitHub に各リポジトリの両方のアーカイブ (Git ソースとメタデータ) を渡す必要があります。

GitHub Enterprise Server 3.7 以前を使用している場合は、GitHub からアクセスできるアーカイブの URL を最初に生成する必要があります。 ほとんどのお客様は、Amazon S3 や Azure Blob Storage などのクラウド プロバイダーの BLOB ストレージ サービスにアーカイブをアップロードし、それぞれについて有効期間の短い URL を生成することを選びます。

GitHub Enterprise Server 3.8 以降を使用している場合は、インスタンスからアーカイブがアップロードされ、URL が生成されます。 前の手順の Location ヘッダーにより、有効期間の短い URL が返されます。

GitHub の IP 範囲を許可リストに加えることが必要になる場合があります。 詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。

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

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

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

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

クエリ変数	説明
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	GitHub Enterprise Cloud 上の移行先 Organization の personal access token。
accessToken	移行元の personal access token。
targetRepoVisibility	新しいリポジトリの可視性。 private、public、または internal にする必要があります。 設定されていない場合、リポジトリはプライベートとして移行されます。
gitArchiveUrl	GitHub Enterprise Cloud でアクセス可能な Git ソース アーカイブの URL。
metadataArchiveUrl	GitHub Enterprise Cloud でアクセス可能なメタデータ アーカイブの URL。
sourceRepositoryUrl	GitHub Enterprise Server インスタンス上のリポジトリの URL。 これは必須ですが、GitHub Enterprise Cloud と GitHub Enterprise Server インスタンスは直接通信しません。

personal access token の要件については、「GitHub 製品間の移行のためのアクセスの管理」をご覧ください。

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

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

移行エラーを検出し、移行が行われていることを確認するには、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。

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

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

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

gh extension upgrade github/gh-gei

{
    "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/*"
            ]
        }
    ]
}

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL \
  --aws-bucket-name AWS-BUCKET-NAME

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL \
  --aws-bucket-name AWS-BUCKET-NAME

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"

gh gei abort-migration --migration-id MIGRATION-ID

gh gei abort-migration --migration-id MIGRATION-ID