Group and project migration by direct transfer API

Version history

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

caution
Migrating projects with this API is in Beta. This feature is not ready for production use.

Prerequisites

For information on prerequisites for group migration by direct transfer API, see prerequisites for migrating groups by direct transfer.

Start a new group or project migration

Version history

Use this endpoint to start a new group or project migration. Specify:

  • entities[group_entity] to migrate a group.
  • entities[project_entity] to migrate a project (Beta).
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. Valid values are group_entity (GitLab 14.2 and later) and project_entity (GitLab 15.11 and later).
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]StringyesDestination 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 or project migrations

GET /bulk_imports
AttributeTypeRequiredDescription
per_pageintegernoNumber of records to return per page.
pageintegernoPage to retrieve.
sortstringnoReturn records 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 group or project migrations’ entities

GET /bulk_imports/entities
AttributeTypeRequiredDescription
per_pageintegernoNumber of records to return per page.
pageintegernoPage to retrieve.
sortstringnoReturn records 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": [
            {
                "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 or project 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 or project migration entities

GET /bulk_imports/:id/entities
AttributeTypeRequiredDescription
per_pageintegernoNumber of records to return per page.
pageintegernoPage to retrieve.
sortstringnoReturn records 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 group or project 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"
}