ファイルエクスポートを使用してプロジェクトとグループを移行する

ファイルエクスポートを使用すると、オフライン環境で動作するGitLabのデータをポータブルパッケージとして入手できます。この移行方法では、リポジトリ、イシュー、マージリクエスト、コメントなど、ほとんどのプロジェクトデータが保持されます。

ファイルエクスポートを使用して以下を行います:

• オフライン環境間を移行します。
• グループ構造全体を含めずに特定のプロジェクトを移動します。

ほとんどの場合、直接転送が推奨される移行方法です。

既知の問題

• 既知のイシューにより、PG::QueryCanceled: ERROR: canceling statement due to statement timeoutエラーが発生する可能性があります。詳細については、トラブルシューティングドキュメントを参照してください。
• GitLab 17.0、17.1、および17.2では、インポートされたエピックと作業アイテムは、元の作成者ではなく、インポートするユーザーにマッピングされます。
• マージリクエストでは、インポートまたはエクスポート時に最新の差分のみが保持されます。プロジェクトをインポートまたはエクスポートした後、マージリクエストでは最新の差分バージョンと最新のパイプラインのみが表示されます。

エクスポートファイルをアップロードしてプロジェクトを移行する

既存のプロジェクトをファイルにエクスポートし、別のGitLabインスタンスにインポートできます。

ユーザーのコントリビュートを保持する

ユーザーのコントリビュートを保持するための要件は、GitLab.comに移行するか、GitLab Self-Managedインスタンスに移行するかによって異なります。

GitLab Self-ManagedからGitLab.comに移行する場合

ファイルエクスポートを使用してプロジェクトを移行する場合、ユーザーのコントリビュートを正しくマッピングするには、管理者のアクセストークンが必要です。

したがって、GitLab Self-ManagedインスタンスからGitLab.comにファイルエクスポートをインポートする場合、ユーザーのコントリビュートが正しくマッピングされることはありません。代わりに、すべてのGitLabユーザーの関連付け(コメントの作成者など)は、プロジェクトをインポートするユーザーに変更されます。コントリビュート履歴を保持するには、次のいずれかを実行します:

• 直接転送を使用して移行します。
• プロフェッショナルサービスのご利用をご検討ください。詳しくは、プロフェッショナルサービスフルカタログをご覧ください。

GitLab Self-Managedに移行する場合

GitLabがユーザーとコントリビュートを正しくマッピングするようにするには:

• プロジェクトのトップレベルグループのオーナーは、プロジェクトにアクセスできるすべてのメンバー(直接および継承された)の情報がエクスポートされたファイルに含められるように、プロジェクトをエクスポートする必要があります。プロジェクトのメンテナーとオーナーは、プロジェクトのエクスポートを開始できます。ただし、プロジェクトの直接メンバーのみがエクスポートされます。
• 管理者がインポートを実行する必要があります。
• 必要なユーザーが、移行先のGitLabインスタンスに存在する必要があります。管理者は、Railsコンソールで一括して、またはUIで1つずつ、確認済みのユーザーを作成できます。
• ユーザーは、送信元のGitLabインスタンスのプロファイルで送信先のGitLabインスタンスのプライマリーメールアドレスと一致する公開メールアドレスをプロファイルに設定する必要があります。プロジェクトのエクスポートファイルを編集して、ユーザーの公開メールアドレスを手動で追加することもできます。
• GitLab 18.4以降 、プロジェクトを既存のグループに直接インポートする際に直接メンバーシップを作成すると、このグループのプロジェクトにユーザーを追加することはできません設定が適用されます。

既存のユーザーのメールアドレスが、インポートされたユーザーのメールアドレスと一致する場合、そのユーザーはインポートされたプロジェクトに直接メンバーとして追加されます。

上記の条件のいずれかが満たされない場合、ユーザーのコントリビュートは正しくマッピングされません。代わりに、すべてのGitLabユーザーの関連付けは、インポートを実行したユーザーに変更されます。そのユーザーは、他のユーザーが作成したマージリクエストの作成者になります。元の作成者に言及している補足コメントは次のとおりです:

• コメント、マージリクエストの承認、リンクされたタスク、アイテムに追加されます。
• マージリクエストまたはイシューの作成者、追加または削除されたラベル、マージ元の情報には追加されません。

プロジェクトのエクスポートファイルを編集する

エクスポートファイルからデータを追加または削除できます。たとえば、次のことができます:

• ユーザーの公開メールアドレスをproject_members.ndjsonファイルに手動で追加します。
• ci_pipelines.ndjsonファイルから行を削除して、CIパイプラインをトリミングします。

プロジェクトのエクスポートファイルを編集するには:

1. エクスポートされた.tar.gzファイルを抽出します。
2. 適切なファイルを編集します。例: tree/project/project_members.ndjson。
3. ファイルを圧縮して.tar.gzファイルに戻します。

project_members.ndjsonファイルを確認して、すべてのメンバーがエクスポートされたことを確認することもできます。

互換性

プロジェクトのエクスポートファイルはNDJSON形式です。

最大2つマイナーバージョン前のGitLabのバージョンからエクスポートされたプロジェクトファイルエクスポートをインポートできます。

次に例を示します:

ファイルエクスポートをインポートソースとして設定する

ファイルエクスポートを使用してGitLab Self-Managedでプロジェクトを移行する前に、GitLab管理者は次のことを行う必要があります:

1. ソースインスタンスでファイルエクスポートを有効にする。
2. 移行先インスタンスのインポートソースとしてファイルエクスポートを有効にします。GitLab.comでは、ファイルエクスポートはすでにインポートソースとして有効になっています。

移行先インスタンスのインポートソースとしてファイルエクスポートを有効にするには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 一般を選択します。
3. 設定のインポートとエクスポートを展開します。
4. ソースをインポートまでスクロールします。
5. GitLabエクスポートチェックボックスを選択します。

CEとEEの間

Community EditionからEnterprise Editionへ、またはその逆にプロジェクトをエクスポートできます（互換性が満たされていると仮定）。

Enterprise EditionからCommunity Editionにプロジェクトをエクスポートすると、Enterprise Editionでのみ保持されているデータを失う可能性があります。詳細については、GitLab Enterprise EditionからCEへのダウングレードを参照してください。

プロジェクトとそのデータをエクスポートする

プロジェクトをインポートする前に、エクスポートする必要があります。

前提要件:

• エクスポートされる項目のリストを確認してください。すべての項目がエクスポートされるわけではありません。
• プロジェクトのメンテナー以上のロールを持っている必要があります。
• 多数のGit参照を持つリポジトリのパフォーマンスを大幅に向上させるには、GitLab 18.0以降を使用してください。技術的な詳細については、GitLabリポジトリのバックアップ時間を短縮することに関するブログ記事を参照してください。

プロジェクトとそのデータをエクスポートするには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > 一般を選択します。
3. 高度な設定を展開します。
4. プロジェクトのエクスポートを選択します:
5. エクスポートが生成されたら、次のことができます:
   • 受信するメールに含まれているリンクをたどります。
   • プロジェクト設定ページを更新し、プロジェクトのエクスポートエリアでエクスポートをダウンロードを選択します。

エクスポートは、設定済みのshared_path（一時的な共有ディレクトリ）で生成され、設定済みのuploads_directoryに移動されます。ワーカーは24時間ごとに、これらのエクスポートファイルを削除します。

エクスポートされるプロジェクトの項目

エクスポートされるプロジェクトの項目は、使用するGitLabのバージョンによって異なります。特定のプロジェクト項目がエクスポートされるかどうかを確認するには:

1. exporters配列を確認してください。
2. GitLabバージョンのプロジェクトのproject/import_export.ymlファイルを確認してください。たとえば、GitLab 16.8の場合はhttps://gitlab.com/gitlab-org/gitlab/-/blob/16-8-stable-ee/lib/gitlab/import_export/project/import_export.ymlです。

簡単な概要として、エクスポートされる項目には次のものがあります:

• プロジェクトリポジトリとWikiリポジトリ
• プロジェクトのアップロード
• プロジェクトの設定（インテグレーションを除く）
• イシュー
  • イシューのコメント
  • イシューのイテレーション（GitLab 15.4で導入）
  • イシューのリソース状態イベント（GitLab 15.4で導入）
  • イシューのリソースマイルストーンイベント（GitLab 15.4で導入）
  • イシューのリソースイテレーションイベント（GitLab 15.4で導入）
• マージリクエスト
  • マージリクエストの差分
  • マージリクエストコメント
  • マージリクエストのリソース状態イベント（GitLab 15.4で導入）
  • マージリクエストの複数の担当者（GitLab 15.3で導入）
  • マージリクエストのレビュアー（GitLab 15.3で導入）
  • マージリクエストの承認者（GitLab 15.3で導入）
• コミットコメント（GitLab 15.10で導入）
• ラベル
• マイルストーン
• スニペット
• リリース
• タイムトラッキングとその他のプロジェクトエンティティ
• 設計管理ファイルとデータ
• LFSオブジェクト
• イシューボード
• CI/CDパイプライン（アーカイブ済み）
• パイプラインスケジュール（無効およびインポートを開始したユーザーに割り当てられている）
• 保護ブランチとタグ
• プッシュルール
• 絵文字リアクション
• プロジェクトの直接メンバー（エクスポートされたプロジェクトのグループのメンテナーロール以上を持っている場合）
• 継承されたプロジェクトメンバーを直接プロジェクトメンバーとして（エクスポートされたプロジェクトのグループのオーナーロールを持っているか、インスタンスへの管理者アクセス権を持っている場合）
• 一部のマージリクエスト承認ルール:
  • 保護ブランチの承認
  • 適格な承認者
• 脆弱性レポート（GitLab 17.7で導入）

エクスポートされないプロジェクトの項目

エクスポートされない項目は次のとおりです:

• 子パイプライン履歴
• パイプラインのトリガー
• CI/CDジョブのトレースとアーティファクト
• パッケージとコンテナレジストリイメージ
• CI/CD変数
• CI/CDジョブトークン許可リスト
• Webhook
• 暗号化されたトークン
• 必要な承認数
• リポジトリのサイズ制限
• 保護ブランチへのプッシュを許可されているデプロイキー
• 安全なファイル
• Git関連イベントのアクティビティーログ
• プロジェクトに関連付けられているセキュリティポリシー
• イシューとリンクされたアイテム間のリンク
• 関連するマージリクエストへのリンク
• パイプラインスケジュール変数

プロジェクトとそのデータをインポートする

プロジェクトとそのデータをインポートできます。インポートできるデータの量は、インポートファイルの最大サイズによって異なります:

• GitLab Self-Managedでは、管理者はインポートファイルの最大サイズを設定できます。
• GitLab.comでは、値は5 GBに設定されています。

前提要件:

• プロジェクトとそのデータをエクスポートする必要があります。
• GitLabのバージョンを比較し、エクスポート元よりも同じかそれ以降のGitLabバージョンにインポートしていることを確認します。
• イシューがないか互換性をレビューします。
• 移行先のグループに対するメンテナーロール以上。

プロジェクトをインポートする

プロジェクトをインポートするには:

1. 左側のサイドバーの上部で、新規作成（ ）と新規プロジェクト/リポジトリを選択します。
2. プロジェクトのインポートを選択します。
3. プロジェクトのインポート元で、GitLabエクスポートを選択します。
4. プロジェクト名とURLを入力します。次に、以前にエクスポートしたファイルを選択します。
5. プロジェクトのインポートを選択します。

APIを使用してインポートの状態をクエリできます。クエリは、インポートエラーまたは例外を返す場合があります。

インポートされたアイテムへの変更

エクスポートされたアイテムは、次の変更を加えてインポートされます:

• オーナーロールを持つプロジェクトメンバーは、メンテナーロールでインポートされます。
• インポートされたプロジェクトにフォークから発生したマージリクエストが含まれている場合、これらのマージリクエストに関連付けられた新しいブランチがプロジェクトに作成されます。したがって、新しいプロジェクトのブランチ数は、ソースプロジェクトよりも多くなる可能性があります。
• Internal表示レベルが制限されている場合、インポートされたすべてのプロジェクトにはPrivate表示レベルが与えられます。

デプロイキーはインポートされません。デプロイキーを使用するには、インポートしたプロジェクトで有効にして、保護ブランチを更新する必要があります。

大規模なプロジェクトをインポートする

大規模なプロジェクトの場合は、Rakeタスクの使用をご検討ください。

インポートファイルの最大サイズを設定する

管理者は、次の2つの方法のいずれかでインポートファイルの最大サイズを設定できます:

• アプリケーション設定APIのmax_import_sizeオプションを使用します。
• 管理者エリアUIで。

デフォルトは0（無制限）です。

レート制限

悪用を避けるため、デフォルトでは、ユーザーは次のレートに制限されています:

エクスポートファイルをアップロードしてグループを移行する（非推奨）

前提要件:

• 移行するグループのオーナーロール。

ファイルのエクスポートを使用すると、次のことができます:

• 任意のグループをファイルにエクスポートし、そのファイルを別のGitLabインスタンス、または同じインスタンス上の別の場所にアップロードできます。
• GitLab UIまたはAPIのいずれかを使用します。
• グループを1つずつ移行し、グループの各プロジェクトを1つずつエクスポートおよびインポートします。

管理者のアクセストークンを使用してインポートを実行すると、GitLabはユーザーのコントリビュートを正しくマップします。GitLab Self-ManagedインスタンスからGitLab.comにインポートする場合、GitLabはユーザーのコントリビュートを正しくマップしません。GitLab Self-ManagedインスタンスからGitLab.comにインポートする際に、Professional Servicesチームの有料サポートを受けると、ユーザーのコントリビュートの正しいマッピングを維持できます。

追加情報

• エクスポートは一時ディレクトリに保存され、特定のワーカーによって24時間ごとに削除されます。
• インポートされたプロジェクトからグループレベルの関係を保持するには、プロジェクトを目的のグループ構造にインポートできるように、最初にグループをエクスポートおよびインポートします。
• 親グループにインポートしない限り、インポートされたグループにはprivateの表示レベルが与えられます。
• 親グループにインポートする場合、サブグループは、別途制限されない限り、同じレベルの表示レベルを継承します。
• Community EditionからEnterprise Edition、またはその逆に、グループをエクスポートできます。Enterprise Editionは、Community Editionには含まれない一部のグループデータを保持します。Enterprise Edition（EE）からCommunity Editionにグループをエクスポートすると、このデータが失われる可能性があります。詳細については、GitLab Enterprise EditionからCEへのダウングレードを参照してください。

インポートファイルの最大サイズは、GitLab Self-Managedにインポートするか、GitLab.comにインポートするかによって異なります:

• GitLab Self-Managedインスタンスにインポートする場合、任意のサイズのインポートファイルをインポートできます。管理者は、次のいずれかを使用してこの動作を変更できます:
  • アプリケーション設定APIのmax_import_sizeオプション。
  • 管理者エリア。
• GitLab.comでは、サイズが5 GB以下のインポートファイルを使用してグループをインポートできます。

互換性

グループファイルのエクスポートはNDJSON形式です。

最大2つマイナーバージョン前のGitLabのバージョンからエクスポートされたグループファイルのエクスポートをインポートできます。

次に例を示します:

エクスポートされるグループ項目

グループのimport_export.ymlファイルには、ファイルエクスポートを使用してグループを移行するときにエクスポートおよびインポートされる項目がリストされます。このファイルをGitLabのバージョンのブランチで表示して、宛先GitLabインスタンスにインポートできる項目を確認します。たとえば、import_export.yml``16-8-stable-eeブランチなどです。

エクスポートされるグループ項目には、次のものがあります:

• マイルストーン
• グループラベル（関連するラベルの優先度なし）
• ボードとボードリスト
• バッジ
• サブグループ（上記のすべてのデータを含む）
• エピック
  • エピックリソースの状態イベント。GitLab 15.4で導入。
• イベント
• Wiki
• イテレーションケイデンス。GitLab 15.4で導入。

エクスポートされないグループ項目

エクスポートされない項目は次のとおりです:

• プロジェクト
• Runnerトークン
• SAML調査トークン
• アップロード

準備

• インポートされたグループのメンバーリストとそれぞれの権限を保持するには、これらのグループのユーザーをレビューしてください。目的のグループをインポートする前に、これらのユーザーが存在することを確認してください。
• ユーザーは、ソースGitLabインスタンスでパブリックメールを設定する必要があります。これは、宛先GitLabインスタンスで確認済みのプライマリメールと一致します。ほとんどのユーザーは、メールアドレスの確認を求めるメールを受信します。

グループのエクスポート

前提要件:

• グループのオーナーロールが必要です。

グループのコンテンツをエクスポートするには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。
2. 設定 > 一般を選択します。
3. 高度な設定セクションで、グループのエクスポートを選択します。
4. エクスポートが生成されたら、次のことができます:
   • 受信するメールに含まれているリンクをたどります。
   • グループ設定ページを更新し、プロジェクトのエクスポートエリアで、エクスポートをダウンロードを選択します。

グループのインポート

グループをインポートするには:

1. 左側のサイドバーの上部で、新規作成（ ）を選択し、新規グループを選択します。
2. グループをインポートを選択します。
3. ファイルからグループをインポートセクションで、グループ名を入力し、関連するグループURLを承認または変更します。
4. ファイルを選択を選択します。
5. インポートするGitLabエクスポートファイルを選択します。
6. インポートを開始するには、インポートを選択します。

レート制限

悪用を避けるため、デフォルトでは、ユーザーは次のレートに制限されています:

関連トピック

• プロジェクトのインポート/エクスポートAPI
• プロジェクトのインポート/エクスポート管理Rakeタスク
• GitLabグループの移行
• グループのインポート/エクスポートAPI
• 直接転送によるグループの移行。