Group migration by direct transfer API

Introduced in GitLab 14.1.

With the group migration by direct transfer API, you can start and view the progress of migrations initiated with group migration by direct transfer.

Start a new group 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 group 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 group 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 group 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 group 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 group 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"
}