グループとプロジェクトをダイレクト転送で移行する

ダイレクト転送を使用してGitLabグループおよびプロジェクトを移行するには:

1. 前提条件を満たしていることを確認してください。
2. ユーザーコントリビュートとユーザーメンバーシップマッピングをレビューします。
3. ソースGitLabインスタンスに接続します。
4. インポートするグループとプロジェクトを選択し、移行を開始します。
5. インポートのレビュー結果。

問題がある場合は、次の操作を実行できます:

1. 移行をキャンセルするか、再試行します。
2. トラブルシューティングドキュメントを参照してください。

前提条件

ダイレクト転送を使用して移行する前に、以下の前提条件を参照してください。

ネットワークとストレージスペース

• インスタンス間またはGitLab.comへのネットワーク接続はHTTPSをサポートしている必要があります。
• ファイアウォールは、ソースと宛先のGitLabインスタンス間の接続をブロックしてはいけません。
• ソースおよび宛先のGitLabインスタンスには、転送されたプロジェクトとグループのアーカイブを作成および抽出するために、/tmpディレクトリに十分な空き容量が必要です。

バージョン

成功し、パフォーマンスの高い移行の可能性を最大化するには:

• ソースおよび宛先の両方のインスタンスをGitLab 16.8以降にアップグレードします。詳細については、エピック9036を参照してください。
• バグ修正やその他の改善のために、可能な限り新しいバージョン間で移行する。

ソースと宛先のインスタンスが同じバージョンではない場合、ソースインスタンスは宛先インスタンスよりも2つのマイナーバージョン以前であってはなりません。この要件は、GitLab.comからGitLab Dedicatedへの移行には適用されません。

設定

• Sidekiqが正しく設定されていることを確認します。
• 両方のGitLabインスタンスで、インスタンス管理者によってダイレクト転送によるグループ移行がアプリケーション設定で有効になっている必要があります。
• ソースGitLabインスタンスに対して、apiスコープを持つパーソナルアクセストークンが必要です。
• ソースおよび宛先のインスタンスで必要な権限を持っている必要があります。下記のとおりです:
  • ほとんどのユーザーの場合、以下が必要です:
    • 移行するソースグループに対するオーナーロール。
    • 宛先ネームスペースでサブグループを作成できるロール。
  • 必要なロールを持たない両方のインスタンスの管理者は、代わりにAPIを使用してインポートを開始できます。
• プロジェクトスニペットをインポートするには、ソースプロジェクトでスニペットが有効になっていることを確認します。
• オブジェクトストレージに保存されているアイテムをインポートするには、次のいずれかの操作を実行する必要があります:
  • proxy_downloadを設定します。
  • 宛先のGitLabインスタンスが、ソースのGitLabインスタンスのオブジェクトストレージにアクセスできることを確認します。
• ソースインスタンスまたはグループがプロジェクトの作成に必要なデフォルトの最小ロールがなしに設定されている場合、プロジェクトを含むグループをインポートできません。必要に応じて、この設定は変更できます:
  • インスタンス全体の場合。
  • 特定のグループの場合。
• 宛先ネームスペース内の既存のマイルストーンと一致するタイトルを持つインポートされたマイルストーンは、インポート時にタイトルが更新されます。新しいタイトルには一意のサフィックスが追加されます。例: 18.0は18.0 (imported-3d-1770206299)になります。これを避けるには、ダイレクト転送を開始する前に、ソースグループまたはプロジェクトのマイルストーンの名前を変更します。
• 次のいずれかを確認してください:
  • ソースおよび宛先のネームスペースが同じ組織に属していること。
  • ソースと宛先のネームスペースが異なる組織に属している場合、どちらの組織も分離済みとしてマークされていないこと。

ユーザーメンバーシップマッピング

移行中にユーザーが作成されることはありません。その代わりに、ソースインスタンスのユーザーメンバーシップは、宛先インスタンスのユーザーにマップされます。ユーザーメンバーシップのマッピングの種類は、ソースインスタンスのメンバーシップタイプによって異なります:

• インポートされたメンバーシップは、初期にプレースホルダーユーザーにマップされます。
• 直接メンバーシップは、宛先インスタンスで直接メンバーシップとしてマップされます。
• 継承されたメンバーシップは、宛先インスタンスで継承されたメンバーシップとしてマップされます。
• 共有メンバーシップは、ユーザーが既存の共有メンバーシップを持っている場合を除き、宛先インスタンスで直接メンバーシップとしてマップされます。共有メンバーシップのマッピングの完全なサポートは、イシュー458345で提案されています。

GitLab 18.4以降では、既存のグループにプロジェクトを直接インポートし、直接メンバーシップを作成する際、このグループのプロジェクトにユーザーを追加することはできません設定が尊重されます。

継承および共有メンバーシップをマッピングする際に、ユーザーが宛先ネームスペースにマップされるものよりも高いロールを持つ既存のメンバーシップを持っている場合、そのメンバーシップは代わりに直接メンバーシップとしてマップされます。これにより、メンバーが高い権限を取得しないようにします。

宛先インスタンスでユーザーを設定する

GitLabがユーザーとそのコントリビュートをソースと宛先のインスタンス間で正しくマップするようにするには:

1. 宛先GitLabインスタンスで必要なユーザーを作成します。管理者アクセスが必要なため、ユーザーはSelf-ManagedインスタンスでのみAPIを使用して作成できます。GitLab.comまたはSelf-Managedインスタンスに移行する場合:
   • ユーザーを手動で作成します。
   • 既存のSAML SSOプロバイダーを設定または使用し、SCIMを通じてサポートされるSAML SSOグループのユーザー同期を活用します。確認済みメールドメインでGitLabユーザーアカウントの確認をバイパスすることができます。
2. ユーザーが、宛先GitLabインスタンス上の確認済みメールアドレスと一致する公開メールをソースGitLabインスタンスに持っていることを確認します。ほとんどのユーザーは、メールアドレスの確認を求めるメールを受信します。
3. ユーザーが宛先インスタンスにすでに存在し、GitLab.comグループにSAML SSOを使用している場合、すべてのユーザーは自分のSAML IDをGitLab.comアカウントにリンクする必要があります。

GitLab UIまたはAPIで、ユーザーの公開メールアドレスを自動的に設定する方法はありません。多数のユーザーアカウントに公開メールアドレスを設定する必要がある場合は、潜在的な回避策についてイシュー284495を参照してください。

ソースGitLabインスタンスを接続する

宛先GitLabインスタンスで、インポートしたいグループを作成し、ソースGitLabインスタンスを接続します:

1. 次のいずれかを作成します:
   • 新しいグループ。右上隅で、新規作成 ( ) と新しいグループを選択します。次にグループをインポートを選択します。
   • 新しいサブグループ。既存のグループページで、次のいずれかを実行します:
     • サブグループを作成を選択します。
     • 右上隅で、新規作成 ( ) と新しいサブグループを選択します。次に、import an existing groupリンクを選択します。
2. GitLabインスタンスのベースURLを入力します。
3. ソースGitLabインスタンスのパーソナルアクセストークンを入力します。
4. インスタンスに接続を選択します。

インポートするグループとプロジェクトを選択します

ソースGitLabインスタンスへのアクセスを承認すると、GitLabグループインポーターページにリダイレクトされます。ここでは、オーナーロールを持つ、接続されたソースインスタンス上のトップレベルグループのリストが表示されます。

ソースインスタンスからすべてのユーザーメンバーシップをインポートしたくない場合は、Import user membershipsチェックボックスがオフになっていることを確認します。たとえば、ソースインスタンスには200人のメンバーがいるかもしれませんが、50人のメンバーのみをインポートしたい場合があります。インポートが完了した後、グループとプロジェクトにメンバーを追加できます。

1. デフォルトでは、提案されるグループネームスペースはソースインスタンスに存在する名前と一致しますが、権限に基づいて、それらのいずれかをインポートする前にこれらの名前を編集することを選択できます。グループおよびプロジェクトのパスは命名規則に準拠する必要があり、インポートの失敗を回避するために必要に応じて正規化されます。
2. インポートしたいグループの横で、次のいずれかを選択します:
   • プロジェクトを含めてインポート。これが利用できない場合は、前提条件を参照してください。
   • プロジェクトを含まずインポート。
3. ステータス列には、各グループのインポートステータスが表示されます。ページを開いたままにすると、リアルタイムで更新されます。
4. グループがインポートされたら、そのGitLabパスを選択して、そのGitLab URLを開きます。

インポートのレビュー結果

インポートの結果をレビューするには:

1. グループインポート履歴ページに移動します。
2. 失敗したインポートの詳細を表示するには、失敗または一部のみが完了のステータスを持つインポートでエラーを表示リンクを選択します。
3. インポートが一部のみが完了または完了のステータスの場合、インポートされたアイテムとインポートされなかったアイテムを確認するには、詳細を表示を選択します。

GitLab UIの一部のアイテムにインポート済みバッジが表示されている場合、アイテムがインポートされたことを確認できます。

グループインポート履歴

グループインポート履歴ページに表示されている、ダイレクト転送によって移行されたすべてのグループを表示できます。該当するのは、次のような場面です:

• ソースグループのパス。
• 宛先グループのパス。
• 各インポートの開始日。
• 各インポートの状態。
• エラーが発生した場合のエラーの詳細。

グループインポート履歴を表示するには:

1. GitLabにサインインします。
2. 右上隅で、新規作成 ( ) と新しいグループを選択します。
3. グループをインポートを選択します。
4. 右上隅で、インポート履歴を表示するを選択します。
5. 特定のインポートでエラーがある場合は、エラーを表示を選択して詳細を確認します。

実行中の移行をキャンセルする

必要に応じて、REST APIまたはRailsコンソールを使用して実行中の移行をキャンセルできます。

REST APIでキャンセルする

REST APIで実行中の移行をキャンセルする方法については、移行をキャンセルを参照してください。

Railsコンソールでキャンセルする

Railsコンソールで実行中の移行をキャンセルするには:

1. 宛先GitLabインスタンスでRailsコンソールセッションを開始します。

2. 次のコマンドを実行して、最後のインポートを見つけます。USER_IDを、インポートを開始したユーザーのユーザーIDに置き換えます:

   bulk_import = BulkImport.where(user_id: USER_ID).last

3. 次のコマンドを実行して、インポートとそれに関連するすべてのアイテムを失敗させます:

   bulk_import.entities.each do |entity|
     entity.trackers.each do |tracker|
       tracker.batches.each(&:fail_op!)
     end
     entity.trackers.each(&:fail_op!)
     entity.fail_op!
   end
   bulk_import.fail_op!

bulk_importをキャンセルしても、ソースインスタンスでプロジェクトをエクスポートするワーカーは停止しませんが、宛先インスタンスが次のことを実行できなくなります:

• ソースインスタンスに、さらにエクスポートするプロジェクトを要求する。
• さまざまなチェックと情報のために、ソースインスタンスに対して他のAPIコールを行う。

失敗した移行または一部成功した移行を再試行する

移行が失敗した場合、または一部成功したがアイテムが不足している場合は、移行を再試行できます。トップレベルグループおよびそのすべてのサブグループとプロジェクト、または特定のサブグループまたはプロジェクトの移行を再試行するには、GitLab UIまたはダイレクト転送APIによるグループおよびプロジェクト移行を使用します。