{{< 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
    }
  }
}

相关主题