通过直接转移进行群组和项目迁移 API

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

History

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

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

使用此 API 迁移项目目前处于 [beta](../policy/development_stages_support.md#beta) 阶段。此功能尚未准备好投入生产使用。

先决条件#

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

启动新的群组或项目迁移#

History

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

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

entities[group_entity] 用于迁移群组。
entities[project_entity] 用于迁移项目。（状态： Beta）

plaintext
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。

shell
1curl --request POST \
2  --url "https://destination-gitlab-instance.example.com/api/v4/bulk_imports" \
3  --header "PRIVATE-TOKEN: <your_access_token_for_destination_gitlab_instance>" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "configuration": {
7      "url": "https://source-gitlab-instance.example.com",
8      "access_token": "<your_access_token_for_source_gitlab_instance>"
9    },
10    "entities": [
11      {
12        "source_full_path": "source/full/path",
13        "source_type": "group_entity",
14        "destination_slug": "destination_slug",
15        "destination_namespace": "destination/namespace/path"
16      }
17    ]
18  }'

json
1{
2  "id": 1,
3  "status": "created",
4  "source_type": "gitlab",
5  "source_url": "https://gitlab.example.com",
6  "created_at": "2021-06-18T09:45:55.358Z",
7  "updated_at": "2021-06-18T09:46:27.003Z",
8  "has_failures": false
9}

列出所有群组或项目迁移#

plaintext
GET /bulk_imports

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

状态可以是以下之一：

created
started
finished
failed

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

json
1[
2    {
3        "id": 1,
4        "status": "finished",
5        "source_type": "gitlab",
6        "source_url": "https://gitlab.example.com",
7        "created_at": "2021-06-18T09:45:55.358Z",
8        "updated_at": "2021-06-18T09:46:27.003Z",
9        "has_failures": false
10    },
11    {
12        "id": 2,
13        "status": "started",
14        "source_type": "gitlab",
15        "source_url": "https://gitlab.example.com",
16        "created_at": "2021-06-18T09:47:36.581Z",
17        "updated_at": "2021-06-18T09:47:58.286Z",
18        "has_failures": false
19    }
20]

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

plaintext
GET /bulk_imports/entities

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

状态可以是以下之一：

created
started
finished
failed

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

json
1[
2    {
3        "id": 1,
4        "bulk_import_id": 1,
5        "status": "finished",
6        "entity_type": "group",
7        "source_full_path": "source_group",
8        "destination_full_path": "destination/full_path",
9        "destination_name": "destination_slug",
10        "destination_slug": "destination_slug",
11        "destination_namespace": "destination_path",
12        "parent_id": null,
13        "namespace_id": 1,
14        "project_id": null,
15        "created_at": "2021-06-18T09:47:37.390Z",
16        "updated_at": "2021-06-18T09:47:51.867Z",
17        "failures": [],
18        "migrate_projects": true,
19        "migrate_memberships": true,
20        "has_failures": false,
21        "stats": {
22            "labels": {
23                "source": 10,
24                "fetched": 10,
25                "imported": 10
26            },
27            "milestones": {
28                "source": 10,
29                "fetched": 10,
30                "imported": 10
31            }
32        }
33    },
34    {
35        "id": 2,
36        "bulk_import_id": 2,
37        "status": "failed",
38        "entity_type": "group",
39        "source_full_path": "another_group",
40        "destination_full_path": "destination/full_path",
41        "destination_name": "destination_slug",
42        "destination_slug": "another_slug",
43        "destination_namespace": "another_namespace",
44        "parent_id": null,
45        "namespace_id": null,
46        "project_id": null,
47        "created_at": "2021-06-24T10:40:20.110Z",
48        "updated_at": "2021-06-24T10:40:46.590Z",
49        "failures": [
50            {
51                "relation": "group",
52                "step": "extractor",
53                "exception_message": "Error!",
54                "exception_class": "Exception",
55                "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd",
56                "created_at": "2021-06-24T10:40:46.495Z",
57                "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline",
58                "pipeline_step": "extractor"
59            }
60        ],
61        "migrate_projects": true,
62        "migrate_memberships": true,
63        "has_failures": false,
64        "stats": { }
65    }
66]

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

plaintext
GET /bulk_imports/:id

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

json
1{
2  "id": 1,
3  "status": "finished",
4  "source_type": "gitlab",
5  "source_url": "https://gitlab.example.com",
6  "created_at": "2021-06-18T09:45:55.358Z",
7  "updated_at": "2021-06-18T09:46:27.003Z"
8}

列出群组或项目迁移实体#

plaintext
GET /bulk_imports/:id/entities

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

状态可以是以下之一：

created
started
finished
failed

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

json
1[
2    {
3        "id": 1,
4        "bulk_import_id": 1,
5        "status": "finished",
6        "entity_type": "group",
7        "source_full_path": "source_group",
8        "destination_full_path": "destination/full_path",
9        "destination_name": "destination_slug",
10        "destination_slug": "destination_slug",
11        "destination_namespace": "destination_path",
12        "parent_id": null,
13        "namespace_id": 1,
14        "project_id": null,
15        "created_at": "2021-06-18T09:47:37.390Z",
16        "updated_at": "2021-06-18T09:47:51.867Z",
17        "failures": [
18            {
19                "relation": "group",
20                "step": "extractor",
21                "exception_message": "Error!",
22                "exception_class": "Exception",
23                "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd",
24                "created_at": "2021-06-24T10:40:46.495Z",
25                "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline",
26                "pipeline_step": "extractor"
27            }
28        ],
29        "migrate_projects": true,
30        "migrate_memberships": true,
31        "has_failures": true,
32        "stats": {
33            "labels": {
34                "source": 10,
35                "fetched": 10,
36                "imported": 10
37            },
38            "milestones": {
39                "source": 10,
40                "fetched": 10,
41                "imported": 10
42            }
43        }
44    }
45]

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

plaintext
GET /bulk_imports/:id/entities/:entity_id

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

json
1{
2    "id": 1,
3    "bulk_import_id": 1,
4    "status": "finished",
5    "entity_type": "group",
6    "source_full_path": "source_group",
7    "destination_full_path": "destination/full_path",
8    "destination_name": "destination_slug",
9    "destination_slug": "destination_slug",
10    "destination_namespace": "destination_path",
11    "parent_id": null,
12    "namespace_id": 1,
13    "project_id": null,
14    "created_at": "2021-06-18T09:47:37.390Z",
15    "updated_at": "2021-06-18T09:47:51.867Z",
16    "failures": [
17        {
18            "relation": "group",
19            "step": "extractor",
20            "exception_message": "Error!",
21            "exception_class": "Exception",
22            "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd",
23            "created_at": "2021-06-24T10:40:46.495Z",
24            "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline",
25            "pipeline_step": "extractor"
26        }
27    ],
28    "migrate_projects": true,
29    "migrate_memberships": true,
30    "has_failures": true,
31    "stats": {
32        "labels": {
33            "source": 10,
34            "fetched": 10,
35            "imported": 10
36        },
37        "milestones": {
38            "source": 10,
39            "fetched": 10,
40            "imported": 10
41        }
42    }
43}

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

History

引入于极狐GitLab 16.6。

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

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

json
1{
2  "relation": "issues",
3  "exception_message": "Error!",
4  "exception_class": "StandardError",
5  "correlation_id_value": "06289e4b064329a69de7bb2d7a1b5a97",
6  "source_url": "https://gitlab.example/project/full/path/-/issues/1",
7  "source_title": "Issue title"
8}

取消迁移#

History

引入于极狐GitLab 17.1。

取消直接传输迁移。

plaintext
POST /bulk_imports/:id/cancel

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

json
1{
2  "id": 1,
3  "status": "canceled",
4  "source_type": "gitlab",
5  "created_at": "2021-06-18T09:45:55.358Z",
6  "updated_at": "2021-06-18T09:46:27.003Z",
7  "has_failures": false
8}

可能的响应状态码：

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