GitLab Migrations (Bulk Imports) API

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