Use this API to schedule and track repository storage moves for groups, projects, and snippets. Project moves cover wiki and design repositories, and group moves cover group wikis. Moving repositories can help you migrate to Gitaly Cluster (Praefect).

To ensure data integrity, GitLab places the group, project, or snippet in a temporary read-only state for the duration of the move. During this time, users receive this message if they try to push new commits:

The repository is temporarily read-only. Please try again later.

This API requires you to authenticate yourself as an administrator.

States

As GitLab processes a storage move, it transitions through different states. Values of state are:

  • initial: The record has been created, but the background job has not yet been scheduled.
  • scheduled: The background job has been scheduled.
  • started: The repositories are being copied to the destination storage.
  • replicated: The repositories have been moved.
  • failed: The repositories failed to copy, or the checksums did not match.
  • finished: The repositories have been moved, and the repositories on the source storage have been deleted.
  • cleanup failed: The repositories have been moved, but the repositories on the source storage could not be deleted.

List all project repository storage moves

GET /api/v4/project_repository_storage_moves

Lists all project repository storage moves.

Parameters

NameTypeDescription
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesProjectsRepositoryStorageMove
400Bad Request—

Create repository storage moves for all projects on a storage shard

POST /api/v4/project_repository_storage_moves

Creates repository storage moves for each project repository stored on the source storage shard. This endpoint migrates all projects at once.

Request body (application/json)

PropertyTypeDescription
destination_storage_nameStringThe destination storage shard
source_storage_name
Required		StringThe source storage shard
Minimum length: 1

Responses

CodeDescriptionSchema
202Accepted—
400Bad Request—

Retrieve a project repository storage move

GET /api/v4/project_repository_storage_moves/{repository_storage_move_id}

Retrieves a specified project repository storage move.

Parameters

NameTypeDescription
repository_storage_move_id
Path, required		IntegerThe ID of a project repository storage move

Responses

CodeDescriptionSchema
200OKAPIEntitiesProjectsRepositoryStorageMove
400Bad Request—
404Not Found—

List all repository storage moves for a project

GET /api/v4/projects/{id}/repository_storage_moves

Lists all repository storage moves for a project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesProjectsRepositoryStorageMove
400Bad Request—
404Not Found—

Create a repository storage move for a project

POST /api/v4/projects/{id}/repository_storage_moves

Creates a repository storage move for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
destination_storage_nameStringThe destination storage shard

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesProjectsRepositoryStorageMove
400Bad Request—
404Not Found—

Retrieve a repository storage move for a project

GET /api/v4/projects/{id}/repository_storage_moves/{repository_storage_move_id}

Retrieves a specified repository storage move for a project.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
repository_storage_move_id
Path, required		IntegerThe ID of a project repository storage move

Responses

CodeDescriptionSchema
200OKAPIEntitiesProjectsRepositoryStorageMove
400Bad Request—
404Not Found—

List all snippet repository storage moves

GET /api/v4/snippet_repository_storage_moves

Lists all snippet repository storage moves. By default, GET requests return 20 results at a time because the API results are paginated.

Parameters

NameTypeDescription
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesSnippetsRepositoryStorageMove
400Bad Request—

Schedule repository storage moves for all snippets on a storage shard

POST /api/v4/snippet_repository_storage_moves

Schedules repository storage moves for each snippet repository stored on the source storage shard. This endpoint migrates all snippets at once.

Request body (application/json)

PropertyTypeDescription
destination_storage_nameStringThe destination storage shard
source_storage_name
Required		StringThe source storage shard
Minimum length: 1

Responses

CodeDescriptionSchema
202Accepted—
400Bad Request—

Retrieve a snippet repository storage move

GET /api/v4/snippet_repository_storage_moves/{repository_storage_move_id}

Retrieves a specified snippet repository storage move.

Parameters

NameTypeDescription
repository_storage_move_id
Path, required		IntegerThe ID of a snippet repository storage move

Responses

CodeDescriptionSchema
200OKAPIEntitiesSnippetsRepositoryStorageMove
400Bad Request—
404Not Found—

List all repository storage moves for a snippet

GET /api/v4/snippets/{id}/repository_storage_moves

Lists all repository storage moves for a specified snippet. By default, GET requests return 20 results at a time because the API results are paginated.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a snippet
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesSnippetsRepositoryStorageMove
400Bad Request—
404Not Found—

Schedule a repository storage move for a snippet

POST /api/v4/snippets/{id}/repository_storage_moves

Schedules a repository storage move for a specified snippet.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a snippet

Request body (application/json)

PropertyTypeDescription
destination_storage_nameStringThe destination storage shard

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesSnippetsRepositoryStorageMove
400Bad Request—
404Not Found—

Retrieve a repository storage move for a snippet

GET /api/v4/snippets/{id}/repository_storage_moves/{repository_storage_move_id}

Retrieves a repository storage move for a specified snippet.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a snippet
repository_storage_move_id
Path, required		IntegerThe ID of a snippet repository storage move

Responses

CodeDescriptionSchema
200OKAPIEntitiesSnippetsRepositoryStorageMove
400Bad Request—
404Not Found—

Schemas

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

APIEntitiesBasicSnippet

PropertyTypeDescription
authorAPIEntitiesUserBasic—
created_atString (date-time)Example: 2012-06-28T10:52:04Z
descriptionStringExample: Ruby test snippet
http_url_to_repoStringExample: https://gitlab.example.com/snippets/65.git
idInteger (int64)Example: 1
project_idInteger (int64)Example: 1
raw_urlStringExample: http://example.com/example/example/snippets/1/raw
ssh_url_to_repoStringExample: ssh://user@gitlab.example.com/snippets/65.git
titleStringExample: test
updated_atString (date-time)Example: 2012-06-28T10:52:04Z
visibilityStringExample: public
web_urlStringExample: http://example.com/example/example/snippets/1

APIEntitiesCustomAttribute

PropertyTypeDescription
keyStringExample: foo
valueStringExample: bar

APIEntitiesProjectIdentity

PropertyTypeDescription
created_atString (date-time)Example: 2020-05-07T04:27:17.016Z
descriptionStringExample: desc
idInteger (int64)Example: 1
nameStringExample: project1
name_with_namespaceStringExample: John Doe / project1
pathStringExample: project1
path_with_namespaceStringExample: namespace1/project1

APIEntitiesProjectsRepositoryStorageMove

PropertyTypeDescription
created_atString (date-time)Example: 2020-05-07T04:27:17.234Z
destination_storage_nameStringExample: storage1
error_messageStringExample: Failed to move repository
idInteger (int64)Example: 1
projectAPIEntitiesProjectIdentity—
source_storage_nameStringExample: default
stateStringExample: scheduled

APIEntitiesSnippetsRepositoryStorageMove

PropertyTypeDescription
created_atString (date-time)Example: 2020-05-07T04:27:17.234Z
destination_storage_nameStringExample: storage1
error_messageStringExample: Failed to move repository
idInteger (int64)Example: 1
snippetAPIEntitiesBasicSnippet—
source_storage_nameStringExample: default
stateStringExample: scheduled

APIEntitiesUserBasic

PropertyTypeDescription
avatar_pathStringExample: /user/avatar/28/The-Big-Lebowski-400-400.png
avatar_urlStringExample: https://gravatar.com/avatar/1
custom_attributesArray of APIEntitiesCustomAttribute—
idInteger (int64)Example: 1
lockedBoolean—
nameStringExample: Administrator
public_emailStringExample: john@example.com
stateStringExample: active
usernameStringExample: admin
web_urlStringExample: https://gitlab.example.com/root
←
REST API / Snippets
REST API / Submodules
→