项目导入和导出 API

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com，私有化部署

使用项目导入和导出 API，通过文件传输导入和导出项目。

在使用项目导入和导出 API 之前，您可能需要使用群组导入和导出 API。

使用项目导入和导出 API 后，您可能需要使用项目级 CI/CD 变量 API。

您仍然必须通过一系列 Docker 拉取和推送迁移您的容器注册表。重新运行任何 CI/CD 流水线以检索任何构建产物。

先决条件#

有关项目导入和导出 API 的先决条件，请参阅：

项目导出的先决条件。
项目导入的先决条件。

安排导出#

开始新的导出。

端点还接受一个 upload 哈希参数。它包含将导出的项目上传到 Web 服务器或任何兼容 S3 平台所需的所有信息。对于导出，极狐GitLab：

仅支持将二进制数据文件上传到最终服务器。
将 Content-Type: application/gzip 头发送给上传请求。确保您的预签名 URL 将此作为签名的一部分。
项目导出过程可能需要一些时间才能完成。确保上传 URL 没有短过期时间，并且在整个导出过程中可用。
管理员可以修改最大导出文件大小。默认情况下，最大值是无限的 (0)。要更改此项，请使用以下方法编辑 max_export_size：
- 极狐GitLab UI。
- 应用程序设置 API
在 JihuLab.com 上导入文件大小有固定限制。有关更多信息，请参阅账户和限制设置。

如果存在 upload 参数，则需要 upload[url] 参数。

plaintext
POST /projects/:id/export

属性	类型	必需	描述
id	整数或字符串	是	项目的 ID 或 URL 编码路径。
upload[url]	字符串	是	项目上传的 URL。
description	字符串	否	覆盖项目描述。
upload	哈希	否	包含信息的哈希以将导出的项目上传到 Web 服务器。
upload[http_method]	字符串	否	上传导出项目的 HTTP 方法。仅允许 PUT 和 POST 方法。默认是 PUT。

shell
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=<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"

json
{
  "message": "202 Accepted"
}

导出状态#

获取导出状态。

plaintext
GET /projects/:id/export

属性	类型	必需	描述
id	整数或字符串	是	项目的 ID 或 URL 编码路径。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/1/export"

状态可以是以下之一：

none: 没有导出排队、开始、完成或 正在重新生成。
queued: 导出请求已接收，并在队列中等待处理。
started: 导出过程已经开始并正在进行中。包括：
- 导出过程。
- 对生成文件执行的操作，例如发送邮件通知用户下载文件，或将导出的文件上传到 Web 服务器。
finished: 导出过程完成后，用户已收到通知。
regeneration_in_progress: 可下载的导出文件，正在处理请求以生成新的导出。

_links 仅在导出完成时出现。

created_at 是项目创建时间戳，而不是导出开始时间。

json
1{
2  "id": 1,
3  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
4  "name": "Gitlab Test",
5  "name_with_namespace": "Gitlab Org / Gitlab Test",
6  "path": "gitlab-test",
7  "path_with_namespace": "gitlab-org/gitlab-test",
8  "created_at": "2017-08-29T04:36:44.383Z",
9  "export_status": "finished",
10  "_links": {
11    "api_url": "https://gitlab.example.com/api/v4/projects/1/export/download",
12    "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/download_export"
13  }
14}

导出下载#

下载已完成的导出。

plaintext
GET /projects/:id/export/download

属性	类型	必需	描述
id	整数或字符串	是	项目的 ID 或 URL 编码路径。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \
     --remote-name "https://gitlab.example.com/api/v4/projects/5/export/download"

shell
ls *export.tar.gz
2017-12-05_22-11-148_namespace_project_export.tar.gz

导入文件#

History

在极狐GitLab 16.0 中引入了对维护者角色的要求，并回移植到极狐GitLab 15.11.1 和极狐GitLab 15.10.5。

plaintext
POST /projects/import

属性	类型	必需	描述
file	字符串	是	要上传的文件。
path	字符串	是	新项目的名称和路径。
name	字符串	否	要导入的项目名称。如果未提供，则默认为项目路径。
namespace	整数或字符串	否	要导入项目的命名空间的 ID 或路径。默认为当前用户的命名空间。需要至少维护者角色才能导入到目标群组。
override_params	哈希	否	支持项目 API 中定义的所有字段。
overwrite	布尔值	否	如果有一个具有相同路径的项目，导入会覆盖它。默认为 false。

传递的覆盖参数优先于导出文件中定义的所有值。

要从文件系统上传文件，请使用 --form 参数。这会导致 cURL 使用 Content-Type: multipart/form-data 头发布数据。file= 参数必须指向文件系统中的文件，并以 @ 前缀。例如：

shell
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 方法导入项目：

python
1import requests
2
3url =  'https://gitlab.example.com/api/v4/projects/import'
4files = { "file": open("project_export.tar.gz", "rb") }
5data = {
6    "path": "example-project",
7    "namespace": "example-group"
8}
9headers = {
10    'Private-Token': "<your_access_token>"
11}
12
13requests.post(url, headers=headers, data=data, files=files)

json
1{
2  "id": 1,
3  "description": null,
4  "name": "api-project",
5  "name_with_namespace": "Administrator / api-project",
6  "path": "api-project",
7  "path_with_namespace": "root/api-project",
8  "created_at": "2018-02-13T09:05:58.023Z",
9  "import_status": "scheduled",
10  "correlation_id": "mezklWso3Za",
11  "failed_relations": []
12}

最大导入文件大小可以由管理员设置。默认是 `0`（无限）。作为管理员，您可以修改最大导入文件大小。要这样做，请在 [应用程序设置 API](settings.md#update-application-settings) 或 [**管理员**区域](../administration/settings/account_and_limit_settings.md)中使用 `max_import_size` 选项。

从远程对象存储导入文件#

状态：Beta

在极狐GitLab 私有化部署中，默认情况下此功能可用。要隐藏该功能，管理员可以[禁用名为 `import_project_from_remote_file` 的功能标志](../administration/feature_flags.md)。在 JihuLab.com 和极狐GitLab Dedicated 中，此功能可用。

plaintext
POST /projects/remote-import

属性	类型	必需	描述
path	字符串	是	新项目的名称和路径。
url	字符串	是	要导入的文件的 URL。
name	字符串	否	要导入的项目名称。如果未提供，则默认为项目路径。
namespace	整数或字符串	否	要导入项目的命名空间的 ID 或路径。默认为当前用户的命名空间。
overwrite	布尔值	否	导入时是否覆盖具有相同路径的项目。默认为 false。
override_params	哈希	否	支持项目 API 中定义的所有字段。

传递的覆盖参数优先于导出文件中定义的所有值。

shell
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"}'

json
1{
2  "id": 1,
3  "description": null,
4  "name": "remote-project",
5  "name_with_namespace": "Administrator / remote-project",
6  "path": "remote-project",
7  "path_with_namespace": "root/remote-project",
8  "created_at": "2018-02-13T09:05:58.023Z",
9  "import_status": "scheduled",
10  "correlation_id": "mezklWso3Za",
11  "failed_relations": [],
12  "import_error": null
13}

Content-Length 头必须返回一个有效数字。最大文件大小为 10 GB。Content-Type 头必须是 application/gzip。

导入单个关系#

History

在 GitLab 16.11 中作为beta引入，使用名为 single_relation_import 的标志。默认禁用。
在 GitLab 17.1 中 GA。功能标志 single_relation_import 已删除。

此端点接受项目导出归档和命名关系（议题、合并请求、流水线或里程碑），并重新导入该关系，跳过已导入的项目。

所需的项目导出文件符合导入文件中描述的结构和大小要求。

提取的文件必须符合极狐GitLab 项目导出的结构。
归档文件不得超过管理员配置的最大导入文件大小。

plaintext
POST /projects/import-relation

属性	类型	必需	描述
file	字符串	是	要上传的文件。
path	字符串	是	新项目的名称和路径。
relation	字符串	是	要导入的关系的名称。必须是 issues、milestones、ci_pipelines 或 merge_requests 之一。

要从文件系统上传文件，请使用 --form 选项，这会导致 cURL 使用 Content-Type: multipart/form-data 头发布数据。file= 参数必须指向文件系统中的文件，并以 @ 前缀。例如：

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

json
1{
2  "id": 9,
3  "project_path": "namespace1/project1",
4  "relation": "issues",
5  "status": "finished"
6}

检查关系导入状态#

History

在极狐GitLab 16.11 中引入。

此端点获取与项目关联的任何关系导入的状态。因为一次只能调度一个关系导入，所以您可以使用此端点检查上一次导入是否成功完成。

plaintext
GET /projects/:id/relation-imports

属性	类型	必需	描述
id	整数或字符串	是	项目的 ID 或 URL 编码路径。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/18/relation-imports"

json
1[
2  {
3    "id": 1,
4    "project_path": "namespace1/project1",
5    "relation": "issues",
6    "status": "created",
7    "created_at": "2024-03-25T11:03:48.074Z",
8    "updated_at": "2024-03-25T11:03:48.074Z"
9  }
10]

状态可以是以下之一：

created: 导入已被调度，但尚未开始。
started: 导入正在处理中。
finished: 导入已完成。
failed: 导入无法完成。

从 AWS S3 导入文件#

History

在 GitLab 15.11 中 GA。功能标志 import_project_from_remote_file_s3 已删除。

plaintext
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 或路径。默认为当前用户的命名空间。

传递的覆盖参数优先于导出文件中定义的所有值。

shell
1curl --request POST \
2  --url "https://gitlab.example.com/api/v4/projects/remote-import-s3" \
3  --header "PRIVATE-TOKEN: <your gitlab access key>" \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "name": "Sample Project",
7  "path": "sample-project",
8  "region": "<Your S3 region name>",
9  "bucket_name": "<Your S3 bucket name>",
10  "file_key": "<Your S3 file key>",
11  "access_key_id": "<Your AWS access key id>",
12  "secret_access_key": "<Your AWS secret access key>"
13}'

此示例从 Amazon S3 存储桶导入，使用连接到 Amazon S3 的模块：

python
1import requests
2from io import BytesIO
3
4s3_file = requests.get(presigned_url)
5
6url =  'https://gitlab.example.com/api/v4/projects/import'
7files = {'file': ('file.tar.gz', BytesIO(s3_file.content))}
8data = {
9    "path": "example-project",
10    "namespace": "example-group"
11}
12headers = {
13    'Private-Token': "<your_access_token>"
14}
15
16requests.post(url, headers=headers, data=data, files=files)

json
1{
2  "id": 1,
3  "description": null,
4  "name": "Sample project",
5  "name_with_namespace": "Administrator / sample-project",
6  "path": "sample-project",
7  "path_with_namespace": "root/sample-project",
8  "created_at": "2018-02-13T09:05:58.023Z",
9  "import_status": "scheduled",
10  "correlation_id": "mezklWso3Za",
11  "failed_relations": [],
12  "import_error": null
13}

导入状态#

获取导入状态。

plaintext
GET /projects/:id/import

属性	类型	必需	描述
id	整数或字符串	是	项目的 ID 或 URL 编码路径。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "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 项。

json
1{
2  "id": 1,
3  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
4  "name": "Gitlab Test",
5  "name_with_namespace": "Gitlab Org / Gitlab Test",
6  "path": "gitlab-test",
7  "path_with_namespace": "gitlab-org/gitlab-test",
8  "created_at": "2017-08-29T04:36:44.383Z",
9  "import_status": "started",
10  "import_type": "github",
11  "correlation_id": "mezklWso3Za",
12  "failed_relations": [
13    {
14      "id": 42,
15      "created_at": "2020-04-02T14:48:59.526Z",
16      "exception_class": "RuntimeError",
17      "exception_message": "A failure occurred",
18      "source": "custom error context",
19      "relation_name": "merge_requests",
20      "line_number": 0
21    }
22  ]
23}

从 GitHub 导入时，stats 字段列出从 GitHub 已获取的对象数量和已导入的对象数量：

json
1{
2  "id": 1,
3  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
4  "name": "Gitlab Test",
5  "name_with_namespace": "Gitlab Org / Gitlab Test",
6  "path": "gitlab-test",
7  "path_with_namespace": "gitlab-org/gitlab-test",
8  "created_at": "2017-08-29T04:36:44.383Z",
9  "import_status": "started",
10  "import_type": "github",
11  "correlation_id": "mezklWso3Za",
12  "failed_relations": [
13    {
14      "id": 42,
15      "created_at": "2020-04-02T14:48:59.526Z",
16      "exception_class": "RuntimeError",
17      "exception_message": "A failure occurred",
18      "source": "custom error context",
19      "relation_name": "merge_requests",
20      "line_number": 0
21    }
22  ],
23  "stats": {
24    "fetched": {
25      "diff_note": 19,
26      "issue": 3,
27      "label": 1,
28      "note": 3,
29      "pull_request": 2,
30      "pull_request_merged_by": 1,
31      "pull_request_review": 16
32    },
33    "imported": {
34      "diff_note": 19,
35      "issue": 3,
36      "label": 1,
37      "note": 3,
38      "pull_request": 2,
39      "pull_request_merged_by": 1,
40      "pull_request_review": 16
41    }
42  }
43}

项目导入和导出 API

先决条件#

安排导出#

导出状态#

导出下载#

导入文件#

从远程对象存储导入文件#

导入单个关系#

检查关系导入状态#

从 AWS S3 导入文件#

导入状态#

相关主题#