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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:::-migration-bucket",
                "arn:aws:s3:::-migration-bucket/*"
            ]
        }
    ]
}

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

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

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

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

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

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

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

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

   メモ

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

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

   メモ

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

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

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

ストレージ アカウントでファイアウォール規則を構成している場合は、移行先の IP 範囲へのアクセスを許可していることを確認します。 「 製品間の移行のためのアクセスの管理」を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mutation startRepositoryMigration (
  $sourceId: ID!,
  $ownerId: ID!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $Pat: String!,
  $gitArchiveUrl: String!,
  $metadataArchiveUrl: String!,
  $sourceRepositoryUrl: URI!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    Pat: $Pat,
    targetRepoVisibility: $targetRepoVisibility
    gitArchiveUrl: $gitArchiveUrl,
    metadataArchiveUrl: $metadataArchiveUrl,
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

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

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

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

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

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

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

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