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

ファイル転送を使用してプロジェクトをインポートおよびエクスポートするには、プロジェクトのインポートおよびエクスポート API を使用します。

プロジェクトのインポート/エクスポート API を使用する前に、グループのインポート/エクスポート API を使用するとよいでしょう。

前提条件

プロジェクトのインポート・エクスポートAPIの前提条件については、こちらをご覧ください:

エクスポートのスケジュール

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

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

  • 最終サーバーへのバイナリデータファイルのアップロードのみをサポートします。
  • アップロードリクエストでContent-Type: application/gzip ヘッダを送信します。署名済みURLに署名の一部としてこれが含まれていることを確認してください。
  • プロジェクトのエクスポート処理を完了するまでに時間がかかることがあります。アップロードURLの有効期限が短くなく、エクスポートプロセス中ずっと利用可能であることを確認してください。
  • 管理者は最大エクスポートファイルサイズを変更できます。デフォルトでは、最大値は無制限です (0)。これを変更するには、max_export_size を編集します:
  • GitLab.comの最大インポートファイルサイズには固定制限があります。詳しくはアカウントと制限の設定をご覧ください。

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

Amazon S3へのアップロードについては、オブジェクトをアップロードするための署名済みURLの生成ドキュメントスクリプトを参照して、upload[url] を生成してください。

POST /projects/:id/export
属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
upload[url]文字列です。yesプロジェクトをアップロードするためのURL。
description文字列です。いいえプロジェクトの説明を上書きします。
uploadハッシュいいえエクスポートしたプロジェクトをWebサーバーにアップロードするための情報を含むハッシュ。
upload[http_method]文字列です。いいえエクスポートしたプロジェクトをアップロードするHTTPメソッド。PUTPOST メソッドのみ使用できます。デフォルトはPUTです。
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
    "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=AKIAIMBJHN2O62W8IELQ%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整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/1/export"

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

  • none:No exports_queued_,started,finished, or_being regenerated_.
  • 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整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \
     --remote-name "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

ファイルのインポート

GitLab16.0で導入され、GitLab15.11.1とGitLab15.10.5にバックポートされたDeveloperロールの代わりにMaintainerロールの要件。

POST /projects/import
属性種類必須説明
file文字列です。yesアップロードするファイル。
path文字列です。yes新しいプロジェクトの名前とパス。
name文字列です。いいえインポートするプロジェクトの名前。省略時はプロジェクトのパスがデフォルトになります。
namespace整数または文字列。いいえプロジェクトをインポートするネームスペースの ID またはパス。デフォルトは現在のユーザーのネームスペースです。

インポート先のグループで少なくともメンテナーのロールが必要です。
override_paramsハッシュいいえ プロジェクトAPIで定義されたすべてのフィールドをサポートします。
overwritebooleanいいえ同じパスのプロジェクトがある場合、インポートはそれを上書きします。デフォルトは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" "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": []
}
note
インポートファイルの最大サイズは管理者が設定できます。デフォルトは0 (無制限) です。管理者として、最大インポートファイルサイズを変更することができます。これを行うには、アプリケーション設定APIまたは管理エリアのmax_import_size 。GitLab 13.8でデフォルトが50MBから0に変更されました。

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

GitLab 13.12ベータ版import_project_from_remote_fileというフラグで導入されました。デフォルトで有効。

フラグ: セルフマネジメントのGitLabでは、デフォルトでこの機能が利用可能です。この機能を隠すには、管理者がimport_project_from_remote_file という機能フラグを無効にします。GitLab.comでは、この機能は利用可能です。

POST /projects/remote-import
属性種類必須説明
path文字列です。yes新しいプロジェクトの名前とパス。
url文字列です。yesインポートするファイルのURL。
name文字列です。いいえインポートするプロジェクトの名前。指定しない場合、デフォルトはプロジェクトのパスになります。
namespace整数または文字列。いいえプロジェクトをインポートするネームスペースの ID またはパス。デフォルトは現在のユーザーのネームスペースです。
overwritebooleanいいえインポート時に同じパスのプロジェクトを上書きするかどうか。デフォルトは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 からのファイルのインポート

POST /projects/remote-import-s3
属性種類必須説明
access_key_id文字列です。yes AWS S3のアクセスキーID
bucket_name文字列です。yesファイルが保存されているAWS S3バケット名
file_key文字列です。yesファイルを識別するためのAWS S3ファイルキー
path文字列です。yes新しいプロジェクトのフルパス。
region文字列です。yesファイルが保存されているAWS S3リージョン名
secret_access_key文字列です。yes 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整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/1/import"

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

  • none
  • scheduled
  • failed
  • started
  • finished

ステータスがfailed の場合、import_error の下にインポートエラーメッセージが含まれます。ステータスがfailedstartedfinishedの場合、failed_relations 配列に、いずれかの理由でインポートに失敗したリレーションが格納されます:

  • 回復不能なエラー。
  • 再試行回数が不足しています。典型的な例:クエリのタイムアウト。
note
failed_relations の要素のid フィールドは、リレーションではなく障害レコードを参照します。

failed_relations 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 からインポートする場合は、astats フィールドに 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
    }
  }
}