オフライン転送を使用してグループとプロジェクトを移行する

オフライン転送は、ソースインスタンスとデスティネーションインスタンス間の直接のネットワーク接続なしに、オブジェクトストレージを介してGitLabのグループとプロジェクトをインスタンス間でコピーします。ソースインスタンスはデータをストレージバケットにエクスポートし、デスティネーションインスタンスは読み取り可能なバケットからデータをインポートします。

デスティネーションインスタンスがソースインスタンスに接続する必要がある直接転送による移行とは異なり、オフライン転送はエクスポートとインポートを分離します。エクスポートバケットとインポートバケットは、同じバケットである必要はなく、同じオブジェクトストレージプロバイダーを使用する必要もありません。デスティネーションインスタンスがエクスポートバケットにアクセスできない場合は、エクスポートファイルをデスティネーションがアクセスできるバケットに移動してください。GitLabはこれらのファイルを移動しません。

オフライン転送は、機能フラグとアプリケーション設定の両方によってゲートされています。これらはすべてデフォルトでオフになっており、特定の操作には両方のレイヤーをオンにする必要があります:

• エクスポート: offline_transfer_exports_enabledアプリケーション設定。
• インポート: offline_transfer_imports_enabledアプリケーション設定。

エクスポートとインポートを実行するには、オフライン転送REST APIを使用します。GitLab UIでのオフライン転送のサポートは、作業アイテム19870で提案されています。

バージョンの要件

オフライン転送エクスポートを作成するには、ソースインスタンスがGitLab 19.3以降を実行している必要があります。エクスポートをインポートするには、デスティネーションインスタンスがGitLab 19.3以降を実行している必要があります。

すべてのエクスポートは、それを作成したソースインスタンスのバージョンを記録します。そのバージョンがデスティネーションインスタンスがサポートする最小バージョンより以前の場合、インポートはUnsupported GitLab versionエラーで失敗します。

サポート対象のオブジェクトストレージプロバイダー

オフライン転送は、以下のオブジェクトストレージプロバイダーをサポートしています:

必要な権限

提供するオブジェクトストレージ認証情報は、以下の権限を持っている必要があります。

AWS S3の場合:

• エクスポート: s3:PutObjectおよびs3:ListBucket
• インポート: s3:GetObjectおよびs3:ListBucket

サービスアカウントを使用したGoogle Cloud Storageの場合:

• エクスポート: storage.buckets.get、storage.objects.create、およびstorage.objects.list
• インポート: storage.objects.get

ADCを使用したGoogle Cloud Storageは、指定するキーではなく、インスタンスのサービスアカウントによって保持される同じ権限を必要とします。

Google Cloud Storage HMACキーはS3相互運用性APIを介して認証するため、storage.*権限ではなく、上記のAWS S3権限が必要です。

他のS3互換プロバイダーの権限は、プロバイダーによって異なります。上記にリストされているAWS S3権限と同等の読み取りおよび書き込み権限でプロバイダーを設定してください。

アプリケーションデフォルト認証情報

ADCを使用したGoogle Cloud Storageは、転送を開始するユーザーとしてではなく、GitLabを実行するインスタンスのサービスアカウントとして認証します。そのサービスアカウントは通常、個々のユーザーよりも特権的であるため、GitLabはADC転送を管理者とgitlab-offline-transfer-で始まる名前のバケットに制限します。

管理者はインスタンスのADCもオンにする必要があります。セキュリティ上の影響と制限の全リストについては、オフライン転送にアプリケーションデフォルト認証情報を許可するを参照してください。

移行されたアイテム

オフライン転送は、直接転送による移行と同じグループおよびプロジェクトアイテムをインポートします。完全なリストについては、移行されたグループアイテムと移行されたプロジェクトアイテムを参照してください。

以下のアイテムはオフライン転送ではインポートされません:

• グループおよびプロジェクトのメンバーシップ。メンバーシップのインポートのサポートは、作業アイテム538356で提案されています。
• Wiki。Wikiのインポートのサポートは、作業アイテム538858で提案されています。
• スニペット。スニペットのインポートのサポートは、作業アイテム538347で提案されています。
• バッジ。バッジのインポートのサポートは、作業アイテム538355で提案されています。

グループをインポートすると、エクスポートに存在する場合、そのサブグループとプロジェクトは常にインポートされます。

ユーザーコントリビュートのマッピング

オフライン転送は、デスティネーションインスタンス上に実際のユーザーを作成することはありません。代わりに、インポートされたコントリビュートはプレースホルダーユーザーにマップされます。インポートが完了したら、プレースホルダーユーザーをデスティネーションインスタンス上のユーザーに再割り当てします。

オフライン転送はグループおよびプロジェクトのメンバーシップをインポートしないため、インポートされたグループおよびプロジェクトにメンバーを自分で追加する必要があります。

表示レベルのルール

オフライン転送は、直接転送による移行と同じ表示レベルルールを適用します。詳細については、表示レベルルールを参照してください。

グループまたはプロジェクトを移行する

前提条件:

• プロジェクトをエクスポートするには、プロジェクトのメンテナーロール以上が必要です。
• グループをエクスポートするには、グループのオーナーロールが必要です。
• グループにインポートするには、デスティネーショングループのオーナーロールが必要です。
• グループをトップレベルグループとしてインポートするには、グループを作成する権限が必要です。
• アプリケーションデフォルト認証情報をエクスポートまたはインポートに使用するには、管理者アクセス権が必要です。

グループまたはプロジェクトを移行する手順:

1. ソースインスタンスで、REST APIを使用してオブジェクトストレージバケットにオフライン転送エクスポートを作成します。
2. エクスポートが完了すると、GitLabはエクスポートプレフィックスを記載したメールを送信します。インポートを開始するにはこのプレフィックスが必要です。メールを受信しない場合、エクスポートプレフィックスはオブジェクトストレージサービスで確認できます。
3. デスティネーションインスタンスがエクスポートバケットにアクセスできない場合は、エクスポートファイルをデスティネーションがアクセスできるバケットに移動してください。
4. デスティネーションインスタンスで、バケットとエクスポートプレフィックスからオフライン転送インポートを作成します。
5. 直接転送APIによるグループおよびプロジェクトの移行でインポートを監視します。

エクスポート全体をインポート

デフォルトでは、オフライン転送インポートには、インポートするすべてのグループまたはプロジェクトとそれらを配置する場所をリストするentities配列が必要です。代わりに、import_allオブジェクトを渡すことで、エクスポート内のすべてのトップレベルグループとそのサブグループおよびプロジェクトをインポートし、デスティネーションネームスペースの下にソースインスタンスの構造を再作成できます。entitiesまたはimport_allのいずれか一方のみが必要です。

エクスポート全体をインポートするには、destination_namespace属性を持つimport_allをオフライン転送インポート作成APIに渡します:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/offline_imports" \
  --data '{
    "bucket": "example-bucket",
    "export_prefix": "example-export-prefix",
    "aws_s3_configuration": {
      "aws_access_key_id": "<aws_access_key_id>",
      "aws_secret_access_key": "<aws_secret_access_key>",
      "region": "us-east-1"
    },
    "import_all": {
      "destination_namespace": "dest-group"
    }
  }'

destination_namespaceを既存のグループのフルパス（例: dest-group/subgroup）に設定して、そのグループの下に構造を再作成します。空の文字列（""）に設定すると、新しいトップレベルグループとして構造が再作成されます。

インポートされるのはトップレベルグループのみです:

• エクスポートに、トップレベルグループ自体がエクスポートされていないパス（例: エクスポートにgroup-a/subgroup-bが含まれるがgroup-aは含まれない）が含まれている場合、GitLabは不足している親グループを作成する代わりにそのパスをスキップします。
• トップレベルグループのパスがデスティネーションネームスペース内の既存のグループと競合する場合、GitLabはそのグループとその下にあるすべてをスキップします。残りのエクスポートは引き続きインポートされます。
• すべてのトップレベルグループが既存のデスティネーションパスと衝突する場合、インポートは失敗します。
• エクスポートにトップレベルグループが含まれていない場合、インポートは失敗します。

直接転送APIによるグループおよびプロジェクトの移行でインポートを監視します。

レート制限

オフライン転送のエクスポートとインポートにはレート制限が適用されます。詳細については、設定不可能なレート制限を参照してください。

関連トピック

• 直接転送を使用してグループとプロジェクトを移行する

トラブルシューティング

オフライン転送を使用して実行された移行で問題が発生した場合は、考えられる解決策について以下のセクションを参照してください。

オブジェクトストレージからエクスポートデータをクリアする

各エクスポートはオブジェクトストレージに新しいプレフィックスを生成するため、あるエクスポートが別のエクスポートを上書きすることはありません。失敗したエクスポートから保存されたデータを削除することは、エクスポートの再試行には必要ありませんが、オブジェクトストレージのコストを削減できる可能性があります。

オブジェクトストレージからエクスポートデータを削除するには、提供したバケットとエクスポートAPIから返されたexport_prefixを使用してデータを特定し、削除します。オブジェクトストレージの設定によっては、これは元に戻せない場合があります。

インポートエラーの特定

• 関連するエラーについては、exceptions_json.logとimporter.logを確認してください。
• Railsコンソールからエラーを抽出する方法については、直接転送による移行のトラブルシューティングを参照してください。

インポートの再試行

インポートを再試行するには:

1. 再試行するグループまたはプロジェクトを削除します。インポート全体を再試行するか、グループまたはプロジェクトのサブセットをターゲットにすることができます:

   • グループをすぐに削除する
   • プロジェクトを直ちに削除する

2. REST APIを使用してインポート全体を再試行するか、entitiesパラメータに以前に失敗したエンティティのみを指定します。