正式なドキュメントは英語版であり、この日本語訳は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インスタンスと宛先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インスタンスのオブジェクトストレージにアクセスできることを確認してください。
  • ソースインスタンスまたはグループのプロジェクトの作成に必要なデフォルトの最小ロールがなしに設定されている場合、プロジェクトを含むグループはインポートできません。必要に応じて、この設定は変更できます:

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

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

  • インポートされたメンバーシップは、最初にプレースホルダユーザーにマップされます。
  • ダイレクトメンバーシップは、宛先インスタンスのダイレクトメンバーシップとしてマップされます。
  • 継承されたメンバーシップは、宛先インスタンスの継承されたメンバーシップとしてマップされます。
  • ユーザーが既存の共有メンバーシップを持っていない限り、共有メンバーシップは宛先インスタンスのダイレクトメンバーシップとしてマップされます。共有メンバーシップのマッピングの完全サポートについては、イシュー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にはありません。多数のユーザーアカウントに公開メールアドレスを設定する必要がある場合は、可能性のある回避策についてissue 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またはGitLab REST APIを使用します。
  • 特定のサブグループまたはプロジェクトの場合は、GitLab REST APIを使用します。