GitLab Migrations (Bulk Imports) API (FREE)

Introduced in GitLab 14.1.

With the GitLab Migrations API, you can view the progress of migrations initiated with GitLab Group Migration.

Start a new GitLab migration

Introduced in GitLab 14.2.

POST /bulk_imports

Attribute	Type	Required	Description
`configuration`	Hash	yes	The source GitLab instance configuration.
`configuration[url]`	String	yes	Source GitLab instance URL.
`configuration[access_token]`	String	yes	Access token to the source GitLab instance.
`entities`	Array	yes	List of entities to import.
`entities[source_type]`	String	yes	Source entity type (only `group_entity` is supported).
`entities[source_full_path]`	String	yes	Source full path of the entity to import.
`entities[destination_name]`	String	yes	Deprecated: Use :destination_slug instead. Destination slug for the entity.
`entities[destination_slug]`	String	yes	Destination slug for the entity.
`entities[destination_namespace]`	String	yes	Destination namespace for the entity.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports" \
  --header "Content-Type: application/json" \
  --data '{
    "configuration": {
      "url": "http://gitlab.example/",
      "access_token": "access_token"
    },
    "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", "created_at": "2021-06-18T09:45:55.358Z", "updated_at": "2021-06-18T09:46:27.003Z" }

List all GitLab migrations

GET /bulk_imports

Attribute	Type	Required	Description
`per_page`	integer	no	Number of records to return per page.
`page`	integer	no	Page to retrieve.
`sort`	string	no	Return GitLab migration sorted in `asc` or `desc` order by creation date. Default is `desc`
`status`	string	no	Import status.

The status can be one of the following:

created
started
finished
failed

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

[
    {
        "id": 1,
        "status": "finished",
        "source_type": "gitlab",
        "created_at": "2021-06-18T09:45:55.358Z",
        "updated_at": "2021-06-18T09:46:27.003Z"
    },
    {
        "id": 2,
        "status": "started",
        "source_type": "gitlab",
        "created_at": "2021-06-18T09:47:36.581Z",
        "updated_at": "2021-06-18T09:47:58.286Z"
    }
]

List all GitLab migrations' entities

GET /bulk_imports/entities

Attribute	Type	Required	Description
`per_page`	integer	no	Number of records to return per page.
`page`	integer	no	Page to retrieve.
`sort`	string	no	Return GitLab migration entities sorted in `asc` or `desc` order by creation date. Default is `desc`
`status`	string	no	Import status.

The status can be one of the following:

created
started
finished
failed

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

[
    {
        "id": 1,
        "bulk_import_id": 1,
        "status": "finished",
        "source_full_path": "source_group",
        "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": []
    },
    {
        "id": 2,
        "bulk_import_id": 2,
        "status": "failed",
        "source_full_path": "another_group",
        "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"
            }
        ]
    }
]

Get GitLab migration details

GET /bulk_imports/:id

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

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

List GitLab migration entities

GET /bulk_imports/:id/entities

Attribute	Type	Required	Description
`per_page`	integer	no	Number of records to return per page.
`page`	integer	no	Page to retrieve.
`sort`	string	no	Return GitLab migration sorted in `asc` or `desc` order by creation date. Default is `desc`
`status`	string	no	Import status.

The status can be one of the following:

created
started
finished
failed

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

[
    {
        "id": 1,
        "status": "finished",
        "source_type": "gitlab",
        "created_at": "2021-06-18T09:45:55.358Z",
        "updated_at": "2021-06-18T09:46:27.003Z"
    }
]

Get GitLab migration entity details

GET /bulk_imports/:id/entities/:entity_id

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

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