{{< details >}}

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

{{< /details >}}

{{< history >}}

  1. 项目迁移引入于极狐GitLab 15.11。

{{< /history >}}

通过直接传输 API 进行群组迁移，您可以启动并查看使用 群组直接传输迁移 发起的迁移的进度。

{{< alert type=”warning” >}}

使用此 API 迁移项目目前处于 beta 阶段。此功能尚未准备好投入生产使用。

{{< /alert >}}

先决条件

有关通过直接传输 API 进行群组迁移的先决条件的信息，请参阅 通过直接传输迁移群组 的先决条件。

启动新的群组或项目迁移

{{< history >}}

  1. project_entity 源类型引入于极狐GitLab 15.11。

{{< /history >}}

使用此端点启动新的群组或项目迁移。请指定：

  • entities[group_entity] 用于迁移群组。
  • entities[project_entity] 用于迁移项目。（状态： Beta）
POST /bulk_imports
属性 类型 必需 描述
configuration Hash 是 源极狐GitLab实例配置。
configuration[url] String 是 源极狐GitLab实例 URL。
configuration[access_token] String 是 源极狐GitLab实例的访问令牌。
entities Array 是 要导入的实体列表。
entities[source_type] String 是 源实体类型。有效值为 group_entity 和 project_entity（极狐GitLab 15.11 及更高版本）。
entities[source_full_path] String 是 要导入实体的源完整路径。例如，gitlab-org/gitlab。
entities[destination_slug] String 是 实体的目标短标识。极狐GitLab 使用短标识作为实体的 URL 路径。导入实体的名称是从源实体的名称复制的，而不是短标识。
entities[destination_name] String 否 已弃用：请改用 destination_slug。实体的目标短标识。
entities[destination_namespace] String 是 实体的目标群组 命名空间 的完整路径。必须是目标实例中现有的群组。
entities[migrate_projects] Boolean 否 也导入群组的所有嵌套项目（如果 source_type 是 group_entity）。默认为 true。
entities[migrate_memberships] Boolean 否 导入用户成员身份。默认为 true。 
curl --request POST \
  --url "https://destination-gitlab-instance.example.com/api/v4/bulk_imports" \
  --header "PRIVATE-TOKEN: <your_access_token_for_destination_gitlab_instance>" \
  --header "Content-Type: application/json" \
  --data '{
    "configuration": {
      "url": "https://source-gitlab-instance.example.com",
      "access_token": "<your_access_token_for_source_gitlab_instance>"
    },
    "entities": [
      {
        "source_full_path": "source/full/path",
        "source_type": "group_entity",
        "destination_slug": "destination_slug",
        "destination_namespace": "destination/namespace/path"
      }
    ]
  }'

{
  "id": 1,
  "status": "created",
  "source_type": "gitlab",
  "source_url": "https://gitlab.example.com",
  "created_at": "2021-06-18T09:45:55.358Z",
  "updated_at": "2021-06-18T09:46:27.003Z",
  "has_failures": false
}

列出所有群组或项目迁移 

GET /bulk_imports
属性 类型 必需 描述
per_page integer 否 每页返回的记录数。
page integer 否 要检索的页。
sort string 否 返回按创建日期 asc 或 desc 顺序排序的记录。默认值为 desc
status string 否 导入状态。

状态可以是以下之一：

  • created
  • started
  • finished
  • failed
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/bulk_imports?per_page=2&page=1"

[
    {
        "id": 1,
        "status": "finished",
        "source_type": "gitlab",
        "source_url": "https://gitlab.example.com",
        "created_at": "2021-06-18T09:45:55.358Z",
        "updated_at": "2021-06-18T09:46:27.003Z",
        "has_failures": false
    },
    {
        "id": 2,
        "status": "started",
        "source_type": "gitlab",
        "source_url": "https://gitlab.example.com",
        "created_at": "2021-06-18T09:47:36.581Z",
        "updated_at": "2021-06-18T09:47:58.286Z",
        "has_failures": false
    }
]

列出所有群组或项目迁移的实体 

GET /bulk_imports/entities
属性 类型 必需 描述
per_page integer 否 每页返回的记录数。
page integer 否 要检索的页。
sort string 否 返回按创建日期 asc 或 desc 顺序排序的记录。默认值为 desc
status string 否 导入状态。

状态可以是以下之一：

  • created
  • started
  • finished
  • failed
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/bulk_imports/entities?per_page=2&page=1&status=started"

[
    {
        "id": 1,
        "bulk_import_id": 1,
        "status": "finished",
        "entity_type": "group",
        "source_full_path": "source_group",
        "destination_full_path": "destination/full_path",
        "destination_name": "destination_slug",
        "destination_slug": "destination_slug",
        "destination_namespace": "destination_path",
        "parent_id": null,
        "namespace_id": 1,
        "project_id": null,
        "created_at": "2021-06-18T09:47:37.390Z",
        "updated_at": "2021-06-18T09:47:51.867Z",
        "failures": [],
        "migrate_projects": true,
        "migrate_memberships": true,
        "has_failures": false,
        "stats": {
            "labels": {
                "source": 10,
                "fetched": 10,
                "imported": 10
            },
            "milestones": {
                "source": 10,
                "fetched": 10,
                "imported": 10
            }
        }
    },
    {
        "id": 2,
        "bulk_import_id": 2,
        "status": "failed",
        "entity_type": "group",
        "source_full_path": "another_group",
        "destination_full_path": "destination/full_path",
        "destination_name": "destination_slug",
        "destination_slug": "another_slug",
        "destination_namespace": "another_namespace",
        "parent_id": null,
        "namespace_id": null,
        "project_id": null,
        "created_at": "2021-06-24T10:40:20.110Z",
        "updated_at": "2021-06-24T10:40:46.590Z",
        "failures": [
            {
                "relation": "group",
                "step": "extractor",
                "exception_message": "Error!",
                "exception_class": "Exception",
                "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd",
                "created_at": "2021-06-24T10:40:46.495Z",
                "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline",
                "pipeline_step": "extractor"
            }
        ],
        "migrate_projects": true,
        "migrate_memberships": true,
        "has_failures": false,
        "stats": { }
    }
]

获取群组或项目迁移详细信息 

GET /bulk_imports/:id

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/bulk_imports/1"

{
  "id": 1,
  "status": "finished",
  "source_type": "gitlab",
  "source_url": "https://gitlab.example.com",
  "created_at": "2021-06-18T09:45:55.358Z",
  "updated_at": "2021-06-18T09:46:27.003Z"
}

列出群组或项目迁移实体 

GET /bulk_imports/:id/entities
属性 类型 必需 描述
per_page integer 否 每页返回的记录数。
page integer 否 要检索的页。
sort string 否 返回按创建日期 asc 或 desc 顺序排序的记录。默认值为 desc
status string 否 导入状态。

状态可以是以下之一：

  • created
  • started
  • finished
  • failed
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/bulk_imports/1/entities?per_page=2&page=1&status=finished"

[
    {
        "id": 1,
        "bulk_import_id": 1,
        "status": "finished",
        "entity_type": "group",
        "source_full_path": "source_group",
        "destination_full_path": "destination/full_path",
        "destination_name": "destination_slug",
        "destination_slug": "destination_slug",
        "destination_namespace": "destination_path",
        "parent_id": null,
        "namespace_id": 1,
        "project_id": null,
        "created_at": "2021-06-18T09:47:37.390Z",
        "updated_at": "2021-06-18T09:47:51.867Z",
        "failures": [
            {
                "relation": "group",
                "step": "extractor",
                "exception_message": "Error!",
                "exception_class": "Exception",
                "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd",
                "created_at": "2021-06-24T10:40:46.495Z",
                "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline",
                "pipeline_step": "extractor"
            }
        ],
        "migrate_projects": true,
        "migrate_memberships": true,
        "has_failures": true,
        "stats": {
            "labels": {
                "source": 10,
                "fetched": 10,
                "imported": 10
            },
            "milestones": {
                "source": 10,
                "fetched": 10,
                "imported": 10
            }
        }
    }
]

获取群组或项目迁移实体详细信息 

GET /bulk_imports/:id/entities/:entity_id

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/bulk_imports/1/entities/2"

{
    "id": 1,
    "bulk_import_id": 1,
    "status": "finished",
    "entity_type": "group",
    "source_full_path": "source_group",
    "destination_full_path": "destination/full_path",
    "destination_name": "destination_slug",
    "destination_slug": "destination_slug",
    "destination_namespace": "destination_path",
    "parent_id": null,
    "namespace_id": 1,
    "project_id": null,
    "created_at": "2021-06-18T09:47:37.390Z",
    "updated_at": "2021-06-18T09:47:51.867Z",
    "failures": [
        {
            "relation": "group",
            "step": "extractor",
            "exception_message": "Error!",
            "exception_class": "Exception",
            "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd",
            "created_at": "2021-06-24T10:40:46.495Z",
            "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline",
            "pipeline_step": "extractor"
        }
    ],
    "migrate_projects": true,
    "migrate_memberships": true,
    "has_failures": true,
    "stats": {
        "labels": {
            "source": 10,
            "fetched": 10,
            "imported": 10
        },
        "milestones": {
            "source": 10,
            "fetched": 10,
            "imported": 10
        }
    }
}

获取群组或项目迁移实体的失败导入记录列表

{{< history >}}

  1. 引入于极狐GitLab 16.6。

{{< /history >}}

GET /bulk_imports/:id/entities/:entity_id/failures

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/bulk_imports/1/entities/2/failures"

{
  "relation": "issues",
  "exception_message": "Error!",
  "exception_class": "StandardError",
  "correlation_id_value": "06289e4b064329a69de7bb2d7a1b5a97",
  "source_url": "https://gitlab.example/project/full/path/-/issues/1",
  "source_title": "Issue title"
}

取消迁移

{{< history >}}

  1. 引入于极狐GitLab 17.1。

{{< /history >}}

取消直接传输迁移。

POST /bulk_imports/:id/cancel

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/bulk_imports/1/cancel"

{
  "id": 1,
  "status": "canceled",
  "source_type": "gitlab",
  "created_at": "2021-06-18T09:45:55.358Z",
  "updated_at": "2021-06-18T09:46:27.003Z",
  "has_failures": false
}

可能的响应状态码：

状态 描述
200 迁移成功取消
401 未授权
403 禁止
404 找不到迁移
503 服务不可用