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

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

このAPIを使用してプロジェクトを移行する。最初にグループのインポート/エクスポートAPIで親グループ構造を移行すると、プロジェクトイシューとグループエピック間の接続など、グループレベルの関係を維持できます。

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

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

前提要件

プロジェクトのインポート/エクスポートAPIの前提条件については、以下を参照してください:

プロジェクトのエクスポートの前提条件。
プロジェクトのインポートの前提条件。

エクスポートをスケジュールする

新しいエクスポートを開始します。

このエンドポイントは、uploadハッシュパラメータも受け入れます。これには、エクスポートされたプロジェクトをWebサーバーまたはS3互換プラットフォームにアップロードするために必要なすべての情報が含まれています。エクスポートの場合、GitLab:

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

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

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

POST /projects/:id/export

属性	型	必須	説明
`id`	整数または文字列	はい	プロジェクトのIDまたはURLエンコードされたパス。
`upload[url]`	文字列	はい	プロジェクトをアップロードするURL。
`description`	文字列	いいえ	プロジェクトの説明をオーバーライドします。
`upload`	ハッシュ	いいえ	エクスポートされたプロジェクトをWebサーバーにアップロードするための情報を含むハッシュ。
`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: エクスポートプロセスが開始され、進行中です。これには以下が含まれます:
- エクスポートのプロセス。
- 結果ファイルに対して実行されるアクション。たとえば、ユーザーにファイルをダウンロードするように通知するメールを送信したり、エクスポートされたファイルをWebサーバーにアップロードしたりします。
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またはパス。デフォルトでは、現在のユーザーのネームスペースになります。インポートするには、宛先グループのメンテナーロールが少なくとも必要です。
`override_params`	ハッシュ	いいえ	Project 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": "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（無制限）に設定されています。管理者は、最大インポートファイルサイズを変更できます。これを行うには、Application設定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またはパス。デフォルトでは、現在のユーザーのネームスペースになります。
`overwrite`	ブール値	いいえ	インポート時に同じパスを持つプロジェクトを上書きするかどうか。`false`がデフォルトです。
`override_params`	ハッシュ	いいえ	Project 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ヘッダーは、有効な数値を返す必要があります。最大ファイルサイズは10GBです。Content-Typeヘッダーはapplication/gzipである必要があります。

単一の関係をインポートする

このエンドポイントは、プロジェクトエクスポートアーカイブと名前付きの関係（イシュー、マージリクエスト、パイプライン、またはマイルストーン）を受け入れ、その関係を再度インポートし、すでにインポートされているアイテムをスキップします。

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

抽出されたファイルは、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: インポートを完了できませんでした。

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またはパス。デフォルトでは、現在のユーザーのネームスペースになります。

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

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": "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
    }
  }
}

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

前提要件

エクスポートをスケジュールする

エクスポートステータス

エクスポートのダウンロード

ファイルをインポートする

リモートオブジェクトストレージからファイルをインポートする

単一の関係をインポートする

関係インポートステータスを確認する

AWS S3からファイルをインポートする

インポートステータス

関連トピック