直接転送を使用したGitLabの移行

GitLabグループは、以下のように移行できます:

• GitLab Self-ManagedおよびGitLab DedicatedからGitLab.comへ
• GitLab.comからGitLab Self-ManagedおよびGitLab Dedicatedへ
• あるGitLab Self-ManagedまたはGitLab Dedicatedインスタンスから別のインスタンスへ
• 同じGitLabインスタンス上

直接転送による移行では、グループの新しいコピーが作成されます。グループをコピーする代わりに移動する場合は、グループが同じGitLabインスタンスにあれば、グループを転送できます。グループの転送は、移行と比べてより高速かつ完全なオプションです。

グループは、次の2つの方法で移行できます:

• 直接転送による方法（推奨）
• エクスポートファイルをアップロードする方法

GitLab.comからGitLab Self-ManagedまたはGitLab Dedicatedインスタンスに移行する場合、管理者はインスタンス上にユーザーを作成できます。

GitLab Self-ManagedおよびGitLab Dedicatedでは、デフォルトでグループ項目の移行は利用できません。管理者は、アプリケーション設定で有効にすることで、この機能を利用できるようになります。

直接転送によるグループの移行では、グループがある場所から別の場所にコピーされます。次のことが可能です:

• 一度に多くのグループをコピーする。
• GitLab UIで、トップレベルグループを以下にコピーする:
  • 別のトップレベルグループ。
  • 既存のトップレベルグループのサブグループ。
  • GitLab.comを含む別のGitLabインスタンス。
• APIで、トップレベルグループとサブグループをこれらの場所にコピーする。
• プロジェクトの有無にかかわらず、グループをコピーします。プロジェクトを含むグループのコピーは、GitLab.comでデフォルトで利用可能です。

すべてのグループおよびプロジェクトリソースがコピーされるわけではありません。コピーされるリソースのリストを以下に示します:

• 移行されるグループ項目。
• 移行されるプロジェクト項目。

移行を開始した後、移行元インスタンスでインポート対象のグループまたはプロジェクトを変更しないでください。これらの変更が移行先インスタンスにコピーされない可能性があります。

フィードバックイシューで、直接転送による移行に関するフィードバックをお寄せください。

特定のプロジェクトを移行する

GitLab UIで直接転送を使用してグループを移行すると、グループ内のすべてのプロジェクトが移行されます。直接転送を使用してグループ内の特定のプロジェクトのみを移行する場合は、APIを使用する必要があります。

既知の問題

• イシュー406685のため、ファイル名が255文字を超えるファイルは移行されません。
• GitLab 16.1以前では、スケジュールされたスキャン実行ポリシーで直接転送を使用しないでください。
• その他の既知の問題のリストについては、エピック6629を参照してください。
• GitLab 16.9以前では、イシュー438422のため、DiffNote::NoteDiffFileCreationErrorエラーが表示されることがあります。このエラーが発生すると、マージリクエストの差分に関するノートの差分が表示されませんが、ノートとマージリクエストは引き続きインポートされます。
• ソースインスタンスからマッピングされる場合、共有メンバーシップが移行先にすでに存在しない限り、共有メンバーは移行先で直接メンバーとしてマッピングされます。つまり、ソースインスタンスのトップレベルグループを移行先のトップレベルグループにインポートすると、ソースのトップレベルグループに必要な共有メンバーシップ階層の詳細が含まれていても、常にプロジェクト内の直接メンバーにマッピングされるということです。共有メンバーシップの完全なマッピングのサポートは、イシュー458345で提案されています。
• GitLab 17.0、17.1、17.2では、インポートされたエピックと作業アイテムは、元の作成者ではなく、インポートするユーザーにマッピングされます。

移行期間を見積もる

直接転送で移行期間を見積もるのは困難です。次の要因が移行期間に影響を与えるためです:

• ソースおよび移行先GitLabインスタンスで使用可能なハードウェアおよびデータベースリソース。ソースおよび移行先インスタンス上のリソースが多いほど、移行期間が短くなる可能性があります。理由は次のとおりです:
  • ソースインスタンスがAPIリクエストを受信し、エクスポートするエンティティを抽出してシリアル化するため。
  • 移行先インスタンスがジョブを実行し、そのデータベースにエンティティを作成するため。
• エクスポートするデータの複雑さとサイズ。たとえば、それぞれに1000件のマージリクエストがある2つの異なるプロジェクトを移行するとします。一方のプロジェクトのマージリクエストに添付ファイル、コメント、その他のアイテムが多数含まれている場合、2つのプロジェクトの移行にかかる時間が大きく異なる可能性があります。したがって、プロジェクトの移行にかかる時間を見積もる際に、プロジェクトのマージリクエストの数はあまり参考になりません。

移行を確実に予測するための正確な手立てはありません。ただし、プロジェクトリレーションをインポートする各パイプラインワーカーの平均時間を見ることで、プロジェクトのインポートにかかる時間を把握しやすくなります:

移行期間を予測するのは困難ですが、以下のような例が参考になるかもしれません:

• 100個のプロジェクト（19.9k件のイシュー、83k件のマージリクエスト、100k+件のパイプライン）を8時間で移行。
• 1926個のプロジェクト（22k件のイシュー、160k件のマージリクエスト、110万件のパイプライン）を34時間で移行。

大規模なプロジェクトを移行していて、タイムアウトや移行期間に関する問題が発生した場合は、移行期間を短縮するを参照してください。

移行期間を短縮する

次に、直接転送を使用した際の移行期間を短縮するためのコツをご紹介します。

移行先インスタンスにSidekiqワーカーを追加する

直接転送を用いた単一の移行では、移行先インスタンスで使用可能なワーカーの数に関係なく、インポートごとに一度に5つのエンティティ（グループまたはプロジェクト）が実行されます。移行先インスタンスのリソースが追加の同時ジョブを処理するのに十分な場合、移行先インスタンス上のSidekiqワーカーを増やすと、各エンティティのインポートにかかる時間を短縮できます。GitLab 16.8以降では、リレーションの一括インポートとエクスポートの導入により、移行先インスタンスで使用可能なワーカーの数がより重要になっています。

移行先インスタンスにSidekiqワーカーを追加する方法の詳細については、Sidekiqの設定を参照してください。

大規模なプロジェクトを再分散させるか、個別に移行を開始する

ソースインスタンス上のワーカーが、（実行中のインポートごとに）5つのエンティティを同時に並行してエクスポートするのに十分な数で存在する必要があります。そうでない場合、移行先はエクスポートされたデータが利用可能になるのを待機することから、遅延やタイムアウトが発生する可能性があります。

異なるグループにプロジェクトを分散させると、タイムアウトを回避できます。同じグループに複数の大規模なプロジェクトがある場合は、以下を実行できます:

1. 大規模なプロジェクトを異なるグループまたはサブグループに移動する。
2. 各グループとサブグループの個別の移行を開始する。

GitLab UIはトップレベルグループのみを移行できます。APIを使用すると、サブグループも移行できます。

制限

直接転送による移行には、ハードコードされた制限が適用されます。

設定可能な制限も利用できます。

GitLab 16.3以降では、以前にハードコードされていた次の設定が設定可能です:

• ソースインスタンスからダウンロードできる最大リレーションサイズ（5 GiBに設定）。
• 解凍されたアーカイブの最大サイズ（10 GiBに設定）。

次のAPIを使用して、最大リレーションサイズ制限をテストできます:

• グループリレーションエクスポートAPI。
• プロジェクトリレーションエクスポートAPI

いずれかのAPIが最大リレーションサイズ制限を超えるファイルを生成すると、直接転送によるグループの移行は失敗します。

表示レベルのルール

移行後は次のようになります:

• プライベートグループとプロジェクトは、プライベートのままです。
• 内部のグループとプロジェクトは次の通りです:
  • 内部の表示レベルが制限されていない限りは、内部グループにコピーされた場合、内部のままです。その場合、グループとプロジェクトはプライベートに変わります。
  • プライベートグループにコピーされると、プライベートに変わります。
• パブリックとなっているグループとプロジェクトは次の通りです:
  • パブリックの表示レベルが制限されていない限りは、パブリックグループにコピーされた場合、パブリックのままです。その場合、グループとプロジェクトは内部になります。
  • 内部の表示レベルが制限されていない限りは、内部グループにコピーされた場合、内部に変わります。その場合、グループとプロジェクトはプライベートに変わります。
  • プライベートグループにコピーされると、プライベートに変わります。

ソースインスタンスでプライベートネットワークを使用してコンテンツを一般公開から隠している場合は、移行先インスタンスでも同様の設定にするか、プライベートグループにインポートするようにしてください。

直接転送プロセスで移行する

直接転送を使用してグループとプロジェクトを移行するを参照してください。