2020-06-10 15:08:07 +00:00
---
stage: Create
group: Gitaly
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-10 15:08:07 +00:00
type: reference
---
2021-01-28 06:08:59 +00:00
# Project repository storage moves API **(FREE SELF)**
2020-05-15 09:07:59 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31285) in GitLab 13.0.
2020-11-02 03:08:43 +00:00
Project repositories including wiki and design repositories can be moved between storages. This can be useful when
2022-06-15 09:09:28 +00:00
[migrating to Gitaly Cluster ](../administration/gitaly/index.md#migrate-to-gitaly-cluster ),
2020-08-27 18:10:29 +00:00
for example.
As project repository storage moves are processed, they transition through different states. Values
of `state` are:
2021-07-02 03:07:23 +00:00
- `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.
2020-08-27 18:10:29 +00:00
2020-10-28 00:08:34 +00:00
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.
2021-06-28 15:08:03 +00:00
This API requires you to [authenticate yourself ](index.md#authentication ) as an administrator.
2020-05-15 09:07:59 +00:00
2021-02-12 15:08:43 +00:00
For other repository types see:
2021-01-14 15:10:46 +00:00
2021-02-12 15:08:43 +00:00
- [Snippet repository storage moves API ](snippet_repository_storage_moves.md ).
- [Group repository storage moves API ](group_repository_storage_moves.md ).
2020-10-29 06:08:45 +00:00
2020-05-15 09:07:59 +00:00
## Retrieve all project repository storage moves
2020-05-20 03:08:04 +00:00
```plaintext
2020-05-15 09:07:59 +00:00
GET /project_repository_storage_moves
```
By default, `GET` requests return 20 results at a time because the API results
2021-06-28 15:08:03 +00:00
are [paginated ](index.md#pagination ).
2020-05-15 09:07:59 +00:00
Example request:
```shell
2020-07-13 21:09:24 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/project_repository_storage_moves"
2020-05-15 09:07:59 +00:00
```
Example response:
```json
[
{
"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"
2021-04-29 12:09:58 +00:00
}
2020-05-15 09:07:59 +00:00
}
]
```
2020-05-29 21:08:35 +00:00
## Retrieve all repository storage moves for a project
```plaintext
GET /projects/:project_id/repository_storage_moves
```
By default, `GET` requests return 20 results at a time because the API results
2021-06-28 15:08:03 +00:00
are [paginated ](index.md#pagination ).
2020-05-29 21:08:35 +00:00
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-06-16 00:08:33 +00:00
| `project_id` | integer | yes | ID of the project |
2020-05-29 21:08:35 +00:00
Example request:
```shell
2020-07-13 21:09:24 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/repository_storage_moves"
2020-05-29 21:08:35 +00:00
```
Example response:
```json
[
{
"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"
2021-04-29 12:09:58 +00:00
}
2020-05-29 21:08:35 +00:00
}
]
```
2020-05-15 09:07:59 +00:00
## Get a single project repository storage move
2020-05-20 03:08:04 +00:00
```plaintext
2020-05-29 21:08:35 +00:00
GET /project_repository_storage_moves/:repository_storage_id
2020-05-15 09:07:59 +00:00
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-06-16 00:08:33 +00:00
| `repository_storage_id` | integer | yes | ID of the project repository storage move |
2020-05-15 09:07:59 +00:00
Example request:
```shell
2020-07-13 21:09:24 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/project_repository_storage_moves/1"
2020-05-15 09:07:59 +00:00
```
Example response:
```json
{
"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"
2021-04-29 12:09:58 +00:00
}
2020-05-15 09:07:59 +00:00
}
```
2020-05-29 21:08:35 +00:00
## Get a single repository storage move for a project
```plaintext
2020-06-16 00:08:33 +00:00
GET /projects/:project_id/repository_storage_moves/:repository_storage_id
2020-05-29 21:08:35 +00:00
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-06-16 00:08:33 +00:00
| `project_id` | integer | yes | ID of the project |
| `repository_storage_id` | integer | yes | ID of the project repository storage move |
2020-05-29 21:08:35 +00:00
Example request:
```shell
2020-07-13 21:09:24 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/repository_storage_moves/1"
2020-06-16 00:08:33 +00:00
```
Example response:
```json
{
"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"
2021-04-29 12:09:58 +00:00
}
2020-06-16 00:08:33 +00:00
}
```
## Schedule a repository storage move for a project
2020-11-02 03:08:43 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34119) in GitLab 13.1.
> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2618) in GitLab 13.3, original repository is automatically removed after successful move and integrity check.
2020-12-04 21:09:29 +00:00
WARNING:
2020-11-02 03:08:43 +00:00
Before GitLab 13.3, a repository move worked more like a repository copy as the
original repository was not deleted from the original storage disk location and
had to be manually cleaned up.
2020-06-16 00:08:33 +00:00
```plaintext
POST /projects/:project_id/repository_storage_moves
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `project_id` | integer | yes | ID of the project |
2021-02-22 21:10:48 +00:00
| `destination_storage_name` | string | no | Name of the destination storage shard. In [GitLab 13.5 and later ](https://gitlab.com/gitlab-org/gitaly/-/issues/3209 ), the storage is selected [automatically based on storage weights ](../administration/repository_storage_paths.md#configure-where-new-repositories-are-stored ) if not provided |
2020-06-16 00:08:33 +00:00
Example request:
```shell
2020-11-05 03:09:03 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " --header "Content-Type: application/json" \
2021-06-02 15:09:59 +00:00
--data '{"destination_storage_name":"storage2"}' \
"https://gitlab.example.com/api/v4/projects/1/repository_storage_moves"
2020-05-29 21:08:35 +00:00
```
Example response:
```json
{
"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"
2021-04-29 12:09:58 +00:00
}
2020-05-29 21:08:35 +00:00
}
```
2020-11-26 12:09:48 +00:00
## Schedule repository storage moves for all projects on a storage shard
2020-11-27 12:09:14 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47142) in GitLab 13.7.
2020-11-26 12:09:48 +00:00
Schedules repository storage moves for each project repository stored on the source storage shard.
```plaintext
POST /project_repository_storage_moves
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `source_storage_name` | string | yes | Name of the source storage shard. |
2021-02-22 21:10:48 +00:00
| `destination_storage_name` | string | no | Name of the destination storage shard. The storage is selected [automatically based on storage weights ](../administration/repository_storage_paths.md#configure-where-new-repositories-are-stored ) if not provided. |
2020-11-26 12:09:48 +00:00
Example request:
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " --header "Content-Type: application/json" \
2021-06-02 15:09:59 +00:00
--data '{"source_storage_name":"default"}' \
"https://gitlab.example.com/api/v4/project_repository_storage_moves"
2020-11-26 12:09:48 +00:00
```
Example response:
```json
{
"message": "202 Accepted"
}
```