Project repository storage moves API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

Project repositories including wiki and design repositories can be moved between storages. This API can help you when migrating to Gitaly Cluster, for example.

As project repository storage moves are processed, they transition 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 project repositories are being copied to the destination storage.
  • replicated: The project has been moved.
  • failed: The project repositories failed to copy or the checksums did not match.
  • finished: The project has been moved and the repositories on the source storage have been deleted.
  • cleanup failed: The project has been moved but the repositories on the source storage could not be deleted.

To ensure data integrity, projects are put in a temporary read-only state for the duration of the move. During this time, users receive a The repository is temporarily read-only. Please try again later. message if they try to push new commits.

This API requires you to authenticate yourself as an administrator.

For other repository types see:

Retrieve all project repository storage moves

GET /project_repository_storage_moves

By default, GET requests return 20 results at a time because the API results are paginated.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_repository_storage_moves"

Example response:

[
  {
    "id": 1,
    "created_at": "2020-05-07T04:27:17.234Z",
    "state": "scheduled",
    "source_storage_name": "default",
    "destination_storage_name": "storage2",
    "project": {
      "id": 1,
      "description": null,
      "name": "project1",
      "name_with_namespace": "John Doe2 / project1",
      "path": "project1",
      "path_with_namespace": "namespace1/project1",
      "created_at": "2020-05-07T04:27:17.016Z"
    }
  }
]

Retrieve all repository storage moves for a project

GET /projects/:project_id/repository_storage_moves

By default, GET requests return 20 results at a time because the API results are paginated.

Parameters:

AttributeTypeRequiredDescription
project_idintegeryesID of the project

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/repository_storage_moves"

Example response:

[
  {
    "id": 1,
    "created_at": "2020-05-07T04:27:17.234Z",
    "state": "scheduled",
    "source_storage_name": "default",
    "destination_storage_name": "storage2",
    "project": {
      "id": 1,
      "description": null,
      "name": "project1",
      "name_with_namespace": "John Doe2 / project1",
      "path": "project1",
      "path_with_namespace": "namespace1/project1",
      "created_at": "2020-05-07T04:27:17.016Z"
    }
  }
]

Get a single project repository storage move

GET /project_repository_storage_moves/:repository_storage_id

Parameters:

AttributeTypeRequiredDescription
repository_storage_idintegeryesID of the project repository storage move

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_repository_storage_moves/1"

Example response:

{
  "id": 1,
  "created_at": "2020-05-07T04:27:17.234Z",
  "state": "scheduled",
  "source_storage_name": "default",
  "destination_storage_name": "storage2",
  "project": {
    "id": 1,
    "description": null,
    "name": "project1",
    "name_with_namespace": "John Doe2 / project1",
    "path": "project1",
    "path_with_namespace": "namespace1/project1",
    "created_at": "2020-05-07T04:27:17.016Z"
  }
}

Get a single repository storage move for a project

GET /projects/:project_id/repository_storage_moves/:repository_storage_id

Parameters:

AttributeTypeRequiredDescription
project_idintegeryesID of the project
repository_storage_idintegeryesID of the project repository storage move

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/repository_storage_moves/1"

Example response:

{
  "id": 1,
  "created_at": "2020-05-07T04:27:17.234Z",
  "state": "scheduled",
  "source_storage_name": "default",
  "destination_storage_name": "storage2",
  "project": {
    "id": 1,
    "description": null,
    "name": "project1",
    "name_with_namespace": "John Doe2 / project1",
    "path": "project1",
    "path_with_namespace": "namespace1/project1",
    "created_at": "2020-05-07T04:27:17.016Z"
  }
}

Schedule a repository storage move for a project

POST /projects/:project_id/repository_storage_moves

Parameters:

AttributeTypeRequiredDescription
project_idintegeryesID of the project
destination_storage_namestringnoName of the destination storage shard. The storage is selected automatically based on storage weights if not provided

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
     --data '{"destination_storage_name":"storage2"}' \
     "https://gitlab.example.com/api/v4/projects/1/repository_storage_moves"

Example response:

{
  "id": 1,
  "created_at": "2020-05-07T04:27:17.234Z",
  "state": "scheduled",
  "source_storage_name": "default",
  "destination_storage_name": "storage2",
  "project": {
    "id": 1,
    "description": null,
    "name": "project1",
    "name_with_namespace": "John Doe2 / project1",
    "path": "project1",
    "path_with_namespace": "namespace1/project1",
    "created_at": "2020-05-07T04:27:17.016Z"
  }
}

Schedule repository storage moves for all projects on a storage shard

Schedules repository storage moves for each project repository stored on the source storage shard. This endpoint migrates all projects at once. For more information, see Move all projects.

POST /project_repository_storage_moves

Parameters:

AttributeTypeRequiredDescription
source_storage_namestringyesName of the source storage shard.
destination_storage_namestringnoName of the destination storage shard. The storage is selected automatically based on storage weights if not provided.

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
     --data '{"source_storage_name":"default"}' \
     "https://gitlab.example.com/api/v4/project_repository_storage_moves"

Example response:

{
  "message": "202 Accepted"
}