Group repository storage moves API

Introduced in GitLab 13.9.

Group repositories can be moved between storages. This can be useful when migrating to Gitaly Cluster, for example, or to migrate a Group Wiki.

As group repository storage moves are processed, they transition through different states. Values of state are:

  • initial
  • scheduled
  • started
  • finished
  • failed
  • replicated
  • cleanup failed

To ensure data integrity, groups 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 type of repositories you can read:

Retrieve all group repository storage moves

GET /group_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/group_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",
    "group": {
      "id": 283,
      "web_url": "https://gitlab.example.com/groups/testgroup",
      "name": "testgroup"
    }
  }
]

Retrieve all repository storage moves for a single group

In order to retrieve all the repository storage moves for a single group you can use the following endpoint:

GET /groups/:group_id/repository_storage_moves

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

Supported attributes:

Attribute Type Required Description
group_id integer yes ID of the group.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/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",
    "group": {
      "id": 283,
      "web_url": "https://gitlab.example.com/groups/testgroup",
      "name": "testgroup"
    }
  }
]

Get a single group repository storage move

In order to retrieve a single repository storage move throughout all the existing repository storage moves, you can use the following endpoint:

GET /group_repository_storage_moves/:repository_storage_id

Supported attributes:

Attribute Type Required Description
repository_storage_id integer yes ID of the group repository storage move.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/group_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",
  "group": {
    "id": 283,
    "web_url": "https://gitlab.example.com/groups/testgroup",
    "name": "testgroup"
  }
}

Get a single repository storage move for a group

Given a group, you can retrieve a specific repository storage move for that group, through the following endpoint:

GET /groups/:group_id/repository_storage_moves/:repository_storage_id

Supported attributes:

Attribute Type Required Description
group_id integer yes ID of the group.
repository_storage_id integer yes ID of the group repository storage move.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/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",
  "group": {
    "id": 283,
    "web_url": "https://gitlab.example.com/groups/testgroup",
    "name": "testgroup"
  }
}

Schedule a repository storage move for a group

POST /groups/:group_id/repository_storage_moves

Supported attributes:

Attribute Type Required Description
group_id integer yes ID of the group.
destination_storage_name string no Name of the destination storage shard. In GitLab 13.5 and later, 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/groups/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",
  "group": {
    "id": 283,
    "web_url": "https://gitlab.example.com/groups/testgroup",
    "name": "testgroup"
  }
}

Schedule repository storage moves for all groups on a storage shard

Schedules repository storage moves for each group repository stored on the source storage shard.

POST /group_repository_storage_moves

Supported attributes:

Attribute Type Required Description
source_storage_name string yes Name of the source storage shard.
destination_storage_name string no Name 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/group_repository_storage_moves"

Example response:

{
  "message": "202 Accepted"
}