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

プロジェクトのインポート/エクスポートAPI

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

このAPIを使用してプロジェクトを移行することができます。まずグループインポートおよびエクスポートAPIで親グループ構造を移行すると、プロジェクトのイシューとグループのエピック間の接続など、グループレベルのリレーションシップを維持できます。

このAPIを使用した後、プロジェクトのCI/CD変数を保持するために、プロジェクトレベルのCI/CD変数APIを使用することをお勧めします。

Dockerのプルとプッシュを繰り返して、コンテナレジストリを移行する必要があります。CI/CDパイプラインを再実行して、ビルドアーティファクトを取得することができます。

前提条件:

プロジェクトをエクスポート

指定したプロジェクトをエクスポートする。

uploadハッシュパラメータを使用して、エクスポートされたプロジェクトをウェブサーバーまたはS3互換のプラットフォームにアップロードします。エクスポートの場合、GitLabは次のとおりです:

  • バイナリデータファイルのアップロードのみを最終サーバーにサポートします。
  • アップロードリクエストとともにContent-Type: application/gzipヘッダーを送信します。署名の一部として、事前署名されたURLにこれを含めるようにしてください。
  • プロジェクトのエクスポートプロセスが完了するまでに時間がかかる場合があります。アップロードURLの有効期限が短すぎず、エクスポートプロセス全体で利用可能であることを確認してください。
  • 管理者は、最大エクスポートファイルサイズを変更できます。デフォルトでは、最大値は無制限（0）です。これを変更するには、次のいずれかを使用してmax_export_sizeを編集します:
  • GitLab.comでの最大インポートファイルサイズに固定の制限があります。詳細については、アカウントと制限設定を参照してください。

uploadパラメータが存在する場合、upload[url]パラメータが必要です。

Amazon S3へのアップロードについては、upload[url]を生成するためのオブジェクトアップロード用の署名済みURL生成ドキュメントスクリプトを参照してください。既知のイシューのため、最大ファイルサイズ5 GBまでのファイルのみをAmazon S3にアップロードできます。

POST /projects/:id/export
属性タイプ必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
upload[url]文字列はいプロジェクトをアップロードするURL。
description文字列いいえプロジェクトの説明をオーバーライドします。
uploadハッシュいいえエクスポートされたプロジェクトをウェブサーバーにアップロードするための情報を含むハッシュ。
upload[http_method]文字列いいえエクスポートされたプロジェクトをアップロードするためのHTTPメソッド。PUTおよびPOSTメソッドのみが許可されます。デフォルトはPUTです。
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/export" \
  --data "upload[http_method]=PUT" \
  --data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<your_access_token>%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd"
{
  "message": "202 Accepted"
}

プロジェクトのエクスポートステータスを取得する

指定したプロジェクトの最新のエクスポートステータスを取得する。

GET /projects/:id/export
属性タイプ必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/export"

ステータスは次のいずれかです:

  • none: キューに入れられたエクスポート、開始されたエクスポート、完了したエクスポート、または再生成中のエクスポートはありません。
  • queued: エクスポートのリクエストが受信され、処理のためにキューに入っています。
  • started: エクスポートプロセスが開始され、進行中です。これには以下が含まれます:
    • エクスポートのプロセス。
    • 結果ファイルに対して実行されるアクション。メールでユーザーにファイルをダウンロードするよう通知したり、エクスポートされたファイルをウェブサーバーにアップロードしたりする場合など。
  • finished: エクスポートプロセスが完了し、ユーザーに通知された後。
  • regeneration_in_progress: エクスポートファイルがダウンロード可能になり、新しいエクスポートを生成するリクエストが処理中です。

_linksは、エクスポートが完了した場合にのみ存在します。

created_atは、プロジェクト作成のタイムスタンプであり、エクスポート開始時間ではありません。

{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "export_status": "finished",
  "_links": {
    "api_url": "https://gitlab.example.com/api/v4/projects/1/export/download",
    "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/download_export"
  }
}

プロジェクトエクスポートをダウンロード

指定したプロジェクトの最新のエクスポートをダウンロードします。

GET /projects/:id/export/download
属性タイプ必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --remote-header-name \
  --remote-name \
  --url "https://gitlab.example.com/api/v4/projects/5/export/download"
ls *export.tar.gz
2017-12-05_22-11-148_namespace_project_export.tar.gz

ローカルアーカイブからプロジェクトをインポート

ローカルアーカイブからプロジェクトをインポートします。

POST /projects/import
属性タイプ必須説明
file文字列はいアップロードするファイル。
path文字列はい新しいプロジェクトの名前とパス。
name文字列いいえインポートするプロジェクトの名前。指定しない場合、プロジェクトのパスにデフォルト設定されます。
namespace整数または文字列いいえ（非推奨）プロジェクトをインポートするネームスペースのIDまたはパス。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。代わりに、namespace_idまたはnamespace_pathを使用してください。
namespace_id整数いいえプロジェクトをインポートするネームスペースのID。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。
namespace_path文字列いいえプロジェクトをインポートするネームスペースのパス。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。
override_paramsハッシュいいえプロジェクトAPIで定義されているすべてのフィールドをサポートします。
overwriteブール値いいえ同じパスのプロジェクトが存在する場合、インポートはそれを上書きするします。falseがデフォルトです。

渡されたオーバーライドパラメータは、エクスポートファイル内で定義されたすべての値よりも優先されます。

ファイルシステムからファイルをアップロードするには、--form引数を使用します。これにより、cURLはヘッダーContent-Type: multipart/form-dataを使用してデータを送信します。file=パラメータは、ファイルシステムのファイルを指しており、先頭に@を付ける必要があります。例:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "path=api-project" \
  --form "file=@/path/to/file" \
  --url "https://gitlab.example.com/api/v4/projects/import"

cURLは、リモートサーバーからのファイル投稿をサポートしていません。この例では、Pythonのopenメソッドを使用してプロジェクトをインポートします:

import requests

url =  'https://gitlab.example.com/api/v4/projects/import'
files = { "file": open("project_export.tar.gz", "rb") }
data = {
    "path": "example-project",
    "namespace_path": "example-group"
}
headers = {
    'Private-Token': "<your_access_token>"
}

requests.post(url, headers=headers, data=data, files=files)
{
  "id": 1,
  "description": null,
  "name": "api-project",
  "name_with_namespace": "Administrator / api-project",
  "path": "api-project",
  "path_with_namespace": "root/api-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": []
}

最大インポートファイルサイズは管理者が設定できます。0（無制限）にデフォルト設定されます。管理者は、最大インポートファイルサイズを変更できます。そのためには、アプリケーション設定APIまたは管理者エリアでmax_import_sizeオプションを使用します。

リモートアーカイブからプロジェクトをインポート

  • ステータス: ベータ版

GitLab Self-Managedでは、この機能はデフォルトで利用可能です。この機能を非表示にするために、管理者はimport_project_from_remote_fileという名前の機能フラグを無効にできます。GitLab.comおよびGitLab Dedicatedでは、この機能を使用できます。

リモートアーカイブからプロジェクトをインポートします。

POST /projects/remote-import
属性タイプ必須説明
path文字列はい新しいプロジェクトの名前とパス。
url文字列はいインポートするファイルのURL。
name文字列いいえインポートするプロジェクトの名前。指定しない場合、プロジェクトのパスにデフォルト設定されます。
namespace整数または文字列いいえ（非推奨）プロジェクトをインポートするネームスペースのIDまたはパス。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。代わりに、namespace_idまたはnamespace_pathを使用してください。
namespace_id整数いいえプロジェクトをインポートするネームスペースのID。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。
namespace_path文字列いいえプロジェクトをインポートするネームスペースのパス。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。
overwriteブール値いいえインポート時に同じパスを持つプロジェクトを上書きするかどうか。falseがデフォルトです。
override_paramsハッシュいいえプロジェクトAPIで定義されているすべてのフィールドをサポートします。

渡されたオーバーライドパラメータは、エクスポートファイル内で定義されたすべての値よりも優先されます。

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/remote-import" \
  --data '{"url":"https://remoteobject/file?token=123123","path":"remote-project"}'
{
  "id": 1,
  "description": null,
  "name": "remote-project",
  "name_with_namespace": "Administrator / remote-project",
  "path": "remote-project",
  "path_with_namespace": "root/remote-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [],
  "import_error": null
}

Content-Lengthヘッダーは有効な数値を返す必要があります。最大ファイルサイズは10 GBです。Content-Typeヘッダーはapplication/gzipである必要があります。

AWS S3バケットからプロジェクトをインポート

指定されたAWS S3バケットに保存されているアーカイブからプロジェクトをインポートします。

POST /projects/remote-import-s3
属性タイプ必須説明
access_key_id文字列はいAWS S3アクセスキーID。
bucket_name文字列はいファイルが保存されているAWS S3バケット名。
file_key文字列はいファイルを識別するためのAWS S3ファイルキー。
path文字列はい新しいプロジェクトのフルパス。
region文字列はいファイルが保存されているAWS S3リージョン名。
secret_access_key文字列はいAWS S3シークレットアクセスキー。
name文字列いいえインポートするプロジェクトの名前。指定しない場合、プロジェクトのパスにデフォルト設定されます。
namespace整数または文字列いいえ（非推奨）プロジェクトをインポートするネームスペースのIDまたはパス。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。代わりに、namespace_idまたはnamespace_pathを使用してください。
namespace_id整数いいえプロジェクトをインポートするネームスペースのID。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。
namespace_path文字列いいえプロジェクトをインポートするネームスペースのパス。現在のユーザーのネームスペースにデフォルト設定されます。

宛先グループでメンテナーまたはオーナーのロールが必要です。

渡されたオーバーライドパラメータは、エクスポートファイル内で定義されたすべての値よりも優先されます。

curl --request POST \
  --url "https://gitlab.example.com/api/v4/projects/remote-import-s3" \
  --header "PRIVATE-TOKEN: <your gitlab access key>" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Sample Project",
  "path": "sample-project",
  "region": "<Your S3 region name>",
  "bucket_name": "<Your S3 bucket name>",
  "file_key": "<Your S3 file key>",
  "access_key_id": "<Your AWS access key id>",
  "secret_access_key": "<Your AWS secret access key>"
}'

この例では、Amazon S3に接続するモジュールを使用して、Amazon S3バケットからインポートします:

import requests
from io import BytesIO

s3_file = requests.get(presigned_url)

url =  'https://gitlab.example.com/api/v4/projects/import'
files = {'file': ('file.tar.gz', BytesIO(s3_file.content))}
data = {
    "path": "example-project",
    "namespace_path": "example-group"
}
headers = {
    'Private-Token': "<your_access_token>"
}

requests.post(url, headers=headers, data=data, files=files)
{
  "id": 1,
  "description": null,
  "name": "Sample project",
  "name_with_namespace": "Administrator / sample-project",
  "path": "sample-project",
  "path_with_namespace": "root/sample-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [],
  "import_error": null
}

プロジェクトインポートのステータスを取得する

指定したプロジェクトの最新のインポートステータスを取得する。

GET /projects/:id/import
属性タイプ必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/import"

ステータスは次のいずれかです:

  • none
  • scheduled
  • failed
  • started
  • finished

ステータスがfailedの場合、import_errorの下にインポートエラーメッセージが含まれます。ステータスがfailed、started、またはfinishedの場合、failed_relations配列には、次のいずれかの理由でインポートに失敗したリレーションの発生が含まれる可能性があります:

  • 回復不可能なエラー。
  • リトライが上限に達しました。典型的な例：クエリタイムアウト。

failed_relations内の要素のidフィールドは、リレーションではなく、失敗レコードを参照します。また、failed_relations配列は100項目に制限されています。

{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "import_status": "started",
  "import_type": "github",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [
    {
      "id": 42,
      "created_at": "2020-04-02T14:48:59.526Z",
      "exception_class": "RuntimeError",
      "exception_message": "A failure occurred",
      "source": "custom error context",
      "relation_name": "merge_requests",
      "line_number": 0
    }
  ]
}

GitHubからインポートする場合、statsフィールドには、GitHubからすでにフェッチされたオブジェクトの数と、すでにインポートされたオブジェクトの数がリストされます:

{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "import_status": "started",
  "import_type": "github",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [
    {
      "id": 42,
      "created_at": "2020-04-02T14:48:59.526Z",
      "exception_class": "RuntimeError",
      "exception_message": "A failure occurred",
      "source": "custom error context",
      "relation_name": "merge_requests",
      "line_number": 0
    }
  ],
  "stats": {
    "fetched": {
      "diff_note": 19,
      "issue": 3,
      "label": 1,
      "note": 3,
      "pull_request": 2,
      "pull_request_merged_by": 1,
      "pull_request_review": 16
    },
    "imported": {
      "diff_note": 19,
      "issue": 3,
      "label": 1,
      "note": 3,
      "pull_request": 2,
      "pull_request_merged_by": 1,
      "pull_request_review": 16
    }
  }
}

プロジェクトリソースをインポート

プロジェクトアーカイブに含まれるプロジェクトリソースをインポートします。インポートするアイテムのタイプは、relation属性によって制御されます。以前にインポートされたアイテムをスキップします。

必要なプロジェクトエクスポートファイルは、ローカルアーカイブからプロジェクトをインポートで説明されているのと同じ構造とサイズ要件に準拠しています。

  • 抽出されたファイルは、GitLabプロジェクトのエクスポートの構造に準拠している必要があります。
  • アーカイブは、管理者によって設定された最大インポートファイルサイズを超えてはなりません。
POST /projects/import-relation
属性タイプ必須説明
file文字列はいアップロードするファイル。
path文字列はい新しいプロジェクトの名前とパス。
relation文字列はいインポートするリレーションの名前。issues、milestones、ci_pipelines、またはmerge_requestsのいずれかである必要があります。

ファイルシステムからファイルをアップロードするには、--formオプションを使用します。これにより、cURLはContent-Type: multipart/form-dataヘッダーを使用してデータを投稿します。file=パラメータは、ファイルシステムのファイルを指しており、先頭に@を付ける必要があります。例:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "path=api-project" \
  --form "file=@/path/to/file" \
  --form "relation=issues" \
  --url "https://gitlab.example.com/api/v4/projects/import-relation"
{
  "id": 9,
  "project_path": "namespace1/project1",
  "relation": "issues",
  "status": "finished"
}

プロジェクトリソースインポートのステータスを取得する

指定したプロジェクトの最新のリレーションインポートのステータスを取得する。一度にスケジュールできるリレーションインポートは1つだけなので、このエンドポイントを使用して、以前のインポートが正常に完了したかどうかを確認できます。

GET /projects/:id/relation-imports
属性タイプ必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/18/relation-imports"
[
  {
    "id": 1,
    "project_path": "namespace1/project1",
    "relation": "issues",
    "status": "created",
    "created_at": "2024-03-25T11:03:48.074Z",
    "updated_at": "2024-03-25T11:03:48.074Z"
  }
]

ステータスは次のいずれかです:

  • created: インポートがスケジュールされましたが、まだ開始されていません。
  • started: インポートが処理中です。
  • finished: インポートが完了しました。
  • failed: インポートを完了できませんでした。