正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

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

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

GitLabのグループとプロジェクトを直接転送を使用して移行するには:

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

問題がある場合は、次の操作が可能です:

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

前提条件

直接転送を使用して移行する前に、以下の前提条件を参照してください。

ネットワークとストレージ領域

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

バージョン

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

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

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

設定

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

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

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

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

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

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

共有メンバーシップのマッピングに影響する既知のイシューがあります。

宛先インスタンスでユーザーを構成する

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

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

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

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

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

  1. 次のいずれかを作成します:
    • 新しいグループ。右上隅で、新規作成 ( plus ) を選択し、新規グループを選択します。次に、グループをインポートを選択します。
    • 新しいサブグループ。既存のグループページで、次のいずれかを行います:
      • サブグループを作成を選択します。
      • 右上隅で、新規作成 ( plus ) を選択し、新しいサブグループを選択します。次に、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. 右上隅で、新規作成 ( plus ) を選択し、新規グループを選択します。
  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によるグループおよびプロジェクトの移行を使用します。