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. For example, gitlab-org/gitlab.
entities[destination_slug]StringyesDestination slug for the entity. GitLab uses the slug as the URL path to the entity. The name of the imported entity is copied from the name of the source entity and not the slug.
entities[destination_name]StringnoDeprecated: Use destination_slug instead. Destination slug for the entity.
entities[destination_namespace]StringyesFull path of the destination group namespace for the entity. Must be an existing group in the destination instance.
entities[migrate_projects]BooleannoAlso import all nested projects of the group (if source_type is group_entity). Defaults to true.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token_for_destination_gitlab_instance>" "https://destination-gitlab-instance.example.com/api/v4/bulk_imports" \
  --header "Content-Type: application/json" \
  --data '{
    "configuration": {
      "url": "https://source-gitlab-instance.example.com",
      "access_token": "<your_access_token_for_source_gitlab_instance>"
    },
    "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": 2,
  "status": "finished",
  "source_type": "gitlab",
  "created_at": "2021-06-18T09:45:55.358Z",
  "updated_at": "2021-06-18T09:46:27.003Z"
}