{{< details >}}
- Tier: 基础版,专业版,旗舰版
- Offering: JihuLab.com,私有化部署
{{< /details >}}
使用项目导入和导出 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
: - 在 JihuLab.com 上导入文件大小有固定限制。有关更多信息,请参阅账户和限制设置。
如果存在 upload
参数,则需要 upload[url]
参数。
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>" \
"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 --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
是项目创建时间戳,而不是导出开始时间。
{
"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 --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
导入文件
{{< history >}}
- 在极狐GitLab 16.0 中引入了对维护者角色的要求,并回移植到极狐GitLab 15.11.1 和极狐GitLab 15.10.5。
{{< /history >}}
POST /projects/import
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
file |
字符串 | 是 | 要上传的文件。 |
path |
字符串 | 是 | 新项目的名称和路径。 |
name |
字符串 | 否 | 要导入的项目名称。如果未提供,则默认为项目路径。 |
namespace |
整数或字符串 | 否 | 要导入项目的命名空间的 ID 或路径。默认为当前用户的命名空间。 需要至少维护者角色才能导入到目标群组。 |
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" "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": []
}
{{< alert type=”note” >}}
最大导入文件大小可以由管理员设置。默认是 0
(无限)。作为管理员,您可以修改最大导入文件大小。要这样做,请在 应用程序设置 API 或 管理员区域中使用 max_import_size
选项。
{{< /alert >}}
从远程对象存储导入文件
{{< details >}}
- 状态:Beta
{{< /details >}}
{{< alert type=”flag” >}}
在极狐GitLab 私有化部署中,默认情况下此功能可用。要隐藏该功能,管理员可以禁用名为 import_project_from_remote_file
的功能标志。在 JihuLab.com 和极狐GitLab Dedicated 中,此功能可用。
{{< /alert >}}
POST /projects/remote-import
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
path |
字符串 | 是 | 新项目的名称和路径。 |
url |
字符串 | 是 | 要导入的文件的 URL。 |
name |
字符串 | 否 | 要导入的项目名称。如果未提供,则默认为项目路径。 |
namespace |
整数或字符串 | 否 | 要导入项目的命名空间的 ID 或路径。默认为当前用户的命名空间。 |
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
。
导入单个关系
{{< history >}}
- 在 GitLab 16.11 中作为beta引入,使用名为
single_relation_import
的标志。默认禁用。 - 在 GitLab 17.1 中 GA。功能标志
single_relation_import
已删除。
{{< /history >}}
此端点接受项目导出归档和命名关系(议题、合并请求、流水线或里程碑),并重新导入该关系,跳过已导入的项目。
所需的项目导出文件符合导入文件中描述的结构和大小要求。
- 提取的文件必须符合极狐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" \
"https://gitlab.example.com/api/v4/projects/import-relation"
{
"id": 9,
"project_path": "namespace1/project1",
"relation": "issues",
"status": "finished"
}
检查关系导入状态
{{< history >}}
- 在极狐GitLab 16.11 中引入。
{{< /history >}}
此端点获取与项目关联的任何关系导入的状态。因为一次只能调度一个关系导入,所以您可以使用此端点检查上一次导入是否成功完成。
GET /projects/:id/relation-imports
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
整数或字符串 | 是 | 项目的 ID 或 URL 编码路径。 |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
"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 导入文件
{{< history >}}
- 在 GitLab 15.11 中 GA。功能标志
import_project_from_remote_file_s3
已删除。
{{< /history >}}
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 --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
数组可能会填充任何由于以下原因而无法导入的关系的出现:
- 不可恢复的错误。
- 重试已耗尽。典型示例:查询超时。
{{< alert type=”note” >}}
failed_relations
中元素的 id
字段引用失败记录,而不是关系。
{{< /alert >}}
{{< alert type=”note” >}}
failed_relations
数组限制为 100 项。
{{< /alert >}}
{
"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
}
}
}