Group repository storage moves API (PREMIUM SELF)

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"
}