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
AttributeTypeRequiredDescription
configurationHashyesThe source GitLab instance configuration.
configuration[url]StringyesSource GitLab instance URL.
configuration[access_token]StringyesAccess token to the source GitLab instance.
entitiesArrayyesList of entities to import.
entities[source_type]StringyesSource entity type (only group_entity is supported).
entities[source_full_path]StringyesSource full path of the entity to import.
entities[destination_name]StringyesDeprecated: Use :destination_slug instead. Destination slug for the entity.
entities[destination_slug]StringyesDestination slug for the entity.
entities[destination_namespace]StringnoDestination namespace for the entity.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports" \
  --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
AttributeTypeRequiredDescription
per_pageintegernoNumber of records to return per page.
pageintegernoPage to retrieve.
sortstringnoReturn GitLab migration sorted in asc or desc order by creation date. Default is desc
statusstringnoImport 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
AttributeTypeRequiredDescription
per_pageintegernoNumber of records to return per page.
pageintegernoPage to retrieve.
sortstringnoReturn GitLab migration entities sorted in asc or desc order by creation date. Default is desc
statusstringnoImport 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": [
            {
                "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline",
                "pipeline_step": "extractor",
                "exception_class": "Exception",
                "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd",
                "created_at": "2021-06-24T10:40:46.495Z"
            }
        ]
    }
]

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
AttributeTypeRequiredDescription
per_pageintegernoNumber of records to return per page.
pageintegernoPage to retrieve.
sortstringnoReturn GitLab migration sorted in asc or desc order by creation date. Default is desc
statusstringnoImport 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"
}