Use this API to migrate groups and projects by using direct transfer, and to import repositories from external sources.

Before migrating by direct transfer, see the prerequisites.

User contribution mapping is not supported when you import projects to a personal namespace. All contributions are assigned to the personal namespace owner and cannot be reassigned.

List all group or project migrations

GET /api/v4/bulk_imports

Lists all group or project migrations.

Parameters

NameTypeDescription
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20
sort
Query		StringReturn GitLab Migrations sorted in created by asc or desc order
Allowed values: asc, desc
Default: desc
status
Query		StringReturn GitLab Migrations with specified status
Allowed values: created, started, finished, timeout, failed, canceled

Responses

CodeDescriptionSchema
200OKAPIEntitiesBulkImport
400Bad Request—
401Unauthorized—
404Not found—
503Service unavailable—

Start a group or project migration

POST /api/v4/bulk_imports

Starts a group or project migration. To migrate a project, specify entities[project_entity].

Request body (application/x-www-form-urlencoded)

PropertyTypeDescription
configuration
Required		ObjectThe source GitLab instance configuration
configuration.access_token
Required		StringAccess token to the source GitLab instance
configuration.url
Required		StringSource GitLab instance URL
entities
Required		Array of objectsList of entities to import
entities[].destination_nameStringDeprecated: Use :destination_slug instead. Destination slug for the entity
Example: 'destination_slug' not 'destination/slug'
entities[].destination_namespace
Required		StringDestination namespace for the entity
Example: 'destination_namespace' or 'destination/namespace'
entities[].destination_slugStringDestination slug for the entity
Example: 'destination_slug' not 'destination/slug'
entities[].migrate_membershipsBooleanThe option to migrate memberships or not
Default: true
entities[].migrate_projectsBooleanIndicates group migration should include nested projects
Default: true
entities[].source_full_path
Required		StringRelative path of the source entity to import
Example: 'source/full/path' not 'https://example.com/source/full/path'
entities[].source_type
Required		StringSource entity type
Allowed values: group_entity, project_entity
Minimum length: 1

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesBulkImport
400Bad request—
401Unauthorized—
404Not found—
422Unprocessable entity—
503Service unavailable—

List all group or project migration entities

GET /api/v4/bulk_imports/entities

Lists all group or project migration entities.

Parameters

NameTypeDescription
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20
sort
Query		StringReturn GitLab Migrations sorted in created by asc or desc order
Allowed values: asc, desc
Default: desc
status
Query		StringReturn all GitLab Migrations’ entities with specified status
Allowed values: created, started, finished, timeout, failed, canceled

Responses

CodeDescriptionSchema
200OKAPIEntitiesBulkImportsEntity
400Bad Request—
401Unauthorized—
404Not found—
503Service unavailable—

Retrieve a group or project migration

GET /api/v4/bulk_imports/{import_id}

Retrieves details of a group or project migration.

Parameters

NameTypeDescription
import_id
Path, required		IntegerThe ID of user’s GitLab Migration

Responses

CodeDescriptionSchema
200OKAPIEntitiesBulkImport
400Bad Request—
401Unauthorized—
404Not found—
503Service unavailable—

Cancel a migration

POST /api/v4/bulk_imports/{import_id}/cancel

Cancels a direct transfer migration. This feature was introduced in GitLab 17.1.

Parameters

NameTypeDescription
import_id
Path, required		IntegerThe ID of user’s GitLab Migration

Responses

CodeDescriptionSchema
200OKAPIEntitiesBulkImport
400Bad Request—
401Unauthorized—
403Forbidden—
404Not found—
503Service unavailable—

List all group or project migration entities

GET /api/v4/bulk_imports/{import_id}/entities

Lists all group or project migration entities for a specified migration.

Parameters

NameTypeDescription
import_id
Path, required		IntegerThe ID of user’s GitLab Migration
status
Query		StringReturn import entities with specified status
Allowed values: created, started, finished, timeout, failed, canceled
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesBulkImportsEntity
400Bad Request—
401Unauthorized—
404Not found—
503Service unavailable—

Retrieve a group or project migration entity

GET /api/v4/bulk_imports/{import_id}/entities/{entity_id}

Retrieves details of a group or project migration entity.

Parameters

NameTypeDescription
import_id
Path, required		IntegerThe ID of user’s GitLab Migration
entity_id
Path, required		IntegerThe ID of GitLab Migration entity

Responses

CodeDescriptionSchema
200OKAPIEntitiesBulkImportsEntity
400Bad Request—
401Unauthorized—
404Not found—
503Service unavailable—

List all failed import records for a migration entity

GET /api/v4/bulk_imports/{import_id}/entities/{entity_id}/failures

Lists all failed import records for a group or project migration entity. This feature was introduced in GitLab 16.6.

Parameters

NameTypeDescription
import_id
Path, required		IntegerThe ID of user’s GitLab Migration
entity_id
Path, required		IntegerThe ID of GitLab Migration entity

Responses

CodeDescriptionSchema
200OKAPIEntitiesBulkImportsEntityFailure
400Bad Request—
401Unauthorized—
404Not found—
503Service unavailable—

Import GitHub gists into GitLab snippets

POST /api/v4/import/github/gists

Imports personal GitHub gists into GitLab snippets. You can import gists with up to 10 files. GitHub gists with more than 10 files are skipped. You should manually migrate these GitHub gists. If any gists cannot be imported, an email is sent with a list of gists that were not imported.

Request body (application/json)

PropertyTypeDescription
personal_access_token
Required		StringGitHub personal access token

Responses

CodeDescriptionSchema
202Accepted—
400Bad Request—
401Unauthorized—
422Unprocessable Entity—
429Too Many Requests—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesBulkImport

PropertyTypeDescription
created_atString (date-time)Example: 2012-05-28T04:42:42-07:00
has_failuresBooleanExample: false
idInteger (int64)Example: 1
source_typeStringExample: gitlab
source_urlStringExample: https://source.gitlab.com/
statusStringAllowed values: created, started, finished, timeout, failed
Example: finished
updated_atString (date-time)Example: 2012-05-28T04:42:42-07:00

APIEntitiesBulkImportsEntity

PropertyTypeDescription
bulk_import_idInteger (int64)Example: 1
created_atString (date-time)Example: 2012-05-28T04:42:42-07:00
destination_full_pathStringExample: some_group/source_project
destination_nameStringExample: destination_slug
destination_namespaceStringExample: destination_path
destination_slugStringExample: destination_slug
entity_typeStringAllowed values: group, project
failuresArray of APIEntitiesBulkImportsEntityFailure—
has_failuresBooleanExample: false
idInteger (int64)Example: 1
migrate_membershipsBooleanExample: true
migrate_projectsBooleanExample: true
namespace_idInteger (int64)Example: 1
parent_idInteger (int64)Example: 1
project_idInteger (int64)Example: 1
source_full_pathStringExample: source_group
statsObject—
statusStringAllowed values: created, started, finished, timeout, failed
Example: created
updated_atString (date-time)Example: 2012-05-28T04:42:42-07:00

APIEntitiesBulkImportsEntityFailure

PropertyTypeDescription
correlation_id_valueStringExample: dfcf583058ed4508e4c7c617bd7f0edd
exception_classStringExample: Exception
exception_messageStringExample: error message
relationStringExample: label
source_titleStringExample: title
source_urlStringExample: https://source.gitlab.com/group/-/epics/1
←
REST API / Hooks
REST API / Instance
→