Repository storage moves
An administrator moves repositories between Gitaly storage shards with storage moves. For each of projects, groups and snippets these actions list every move, list the moves of one, read a move, schedule one, and schedule moves for every repository on a shard. Group moves are served from Premium.
Sample questions
Section titled “Sample questions”- “List the project storage moves in progress”
- “Move project 42 to the storage2 shard”
- “What is the state of group storage move 7?”
How to call it
Section titled “How to call it”- Dynamic, the default surface: call
gitlab_execute_actionwithactionset to the action’s ID, such asstorage_move.get_group, and its parameters inparams.gitlab_find_actionfinds an ID from a description of the task. - Meta (
GITLAB_MCP_TOOL_SURFACE=meta): callgitlab_storage_movewithactionset to the action’s name, such asget_group, and its parameters inparams. - Individual (
GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such asgitlab_get_group_storage_move, with its parameters as the arguments.
Availability
Section titled “Availability”How many of these actions an instance serves at each tier, out of a total of 18:
- Free: 12
- Premium: 18
- Ultimate: 18
Listed only for a token that carries admin_mode: the server removes the group from every surface for a token whose scopes it knows and that lacks it.
Read-only actions: 12 of 18, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 12 of the 18.
Actions
Section titled “Actions”The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served. The token lines say what GitLab 19.4.1 requires of a token for the requests each action sends; on an instance with Admin Mode turned on, an action only an administrator may run also needs admin_mode.
| Action | Tier | Individual |
|---|---|---|
storage_move.get_group | Premium | gitlab_get_group_storage_move |
storage_move.get_group_for_group | Premium | gitlab_get_group_storage_move_for_group |
storage_move.get_project | Free | gitlab_get_project_storage_move |
storage_move.get_project_for_project | Free | gitlab_get_project_storage_move_for_project |
storage_move.get_snippet | Free | gitlab_get_snippet_storage_move |
storage_move.get_snippet_for_snippet | Free | gitlab_get_snippet_storage_move_for_snippet |
storage_move.retrieve_all_group | Premium | gitlab_retrieve_all_group_storage_moves |
storage_move.retrieve_all_project | Free | gitlab_retrieve_all_project_storage_moves |
storage_move.retrieve_all_snippet | Free | gitlab_retrieve_all_snippet_storage_moves |
storage_move.retrieve_group | Premium | gitlab_retrieve_group_storage_moves |
storage_move.retrieve_project | Free | gitlab_retrieve_project_storage_moves |
storage_move.retrieve_snippet | Free | gitlab_retrieve_snippet_storage_moves |
storage_move.schedule_all_group | Premium | gitlab_schedule_all_group_storage_moves |
storage_move.schedule_all_project | Free | gitlab_schedule_all_project_storage_moves |
storage_move.schedule_all_snippet | Free | gitlab_schedule_all_snippet_storage_moves |
storage_move.schedule_group | Premium | gitlab_schedule_group_storage_move |
storage_move.schedule_project | Free | gitlab_schedule_project_storage_move |
storage_move.schedule_snippet | Free | gitlab_schedule_snippet_storage_move |
storage_move.get_group
Section titled “storage_move.get_group”Get a single group repository storage move by ID. Returns: the storage move with state, source and destination storage names, group reference, and creation time. See also:
storage_move.retrieve_all_group,storage_move.get_group_for_group.
- Meta-tool:
gitlab_storage_move, actionget_group - Individual tool:
gitlab_get_group_storage_move - Tier: Premium
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at instance (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
id | integer | yes | Numeric ID of the storage move |
storage_move.get_group_for_group
Section titled “storage_move.get_group_for_group”Get a single repository storage move for a specific group. Returns: the storage move with state, source and destination storage names, group reference, and creation time. See also:
storage_move.retrieve_group,storage_move.get_group.
- Meta-tool:
gitlab_storage_move, actionget_group_for_group - Individual tool:
gitlab_get_group_storage_move_for_group - Tier: Premium
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at group (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
group_id | integer | yes | Numeric ID of the group |
id | integer | yes | Numeric ID of the storage move |
storage_move.get_project
Section titled “storage_move.get_project”Get a single project repository storage move by its global move id. Returns: the move’s id, state, source and destination storage shards, and project. Admin-only and self-managed only. See also:
storage_move.retrieve_all_project.
- Meta-tool:
gitlab_storage_move, actionget_project - Individual tool:
gitlab_get_project_storage_move - Tier: Free
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at instance (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
id | integer | yes | Numeric ID of the storage move |
storage_move.get_project_for_project
Section titled “storage_move.get_project_for_project”Get a single repository storage move for a specific project by project_id and move id. Returns: the move’s id, state, source and destination storage shards, and project. Admin-only and self-managed only. See also:
storage_move.retrieve_project.
- Meta-tool:
gitlab_storage_move, actionget_project_for_project - Individual tool:
gitlab_get_project_storage_move_for_project - Tier: Free
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at project (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
id | integer | yes | Numeric ID of the storage move |
project_id | integer | yes | Numeric ID of the project |
storage_move.get_snippet
Section titled “storage_move.get_snippet”Get a single snippet repository storage move by its ID. Returns: the storage move with state, source and destination storage shards, and the associated snippet. See also:
storage_move.retrieve_all_snippet,storage_move.get_snippet_for_snippet.
- Meta-tool:
gitlab_storage_move, actionget_snippet - Individual tool:
gitlab_get_snippet_storage_move - Tier: Free
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at instance (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
id | integer | yes | Numeric ID of the storage move |
storage_move.get_snippet_for_snippet
Section titled “storage_move.get_snippet_for_snippet”Get a single repository storage move scoped to one snippet by snippet ID and move ID. Returns: the storage move with state, source and destination storage shards, and the associated snippet. See also:
storage_move.retrieve_snippet,storage_move.get_snippet.
- Meta-tool:
gitlab_storage_move, actionget_snippet_for_snippet - Individual tool:
gitlab_get_snippet_storage_move_for_snippet - Tier: Free
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at instance (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
id | integer | yes | Numeric ID of the storage move |
snippet_id | integer | yes | Numeric ID of the snippet |
storage_move.retrieve_all_group
Section titled “storage_move.retrieve_all_group”List all group repository storage moves across the instance. Returns: storage moves with state, source and destination storage names, group reference, creation time, and pagination metadata. See also:
storage_move.retrieve_group,storage_move.get_group,storage_move.schedule_all_group.
- Meta-tool:
gitlab_storage_move, actionretrieve_all_group - Individual tool:
gitlab_retrieve_all_group_storage_moves - Tier: Premium
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at instance (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
order_by | string | no | Column to order keyset-paginated results by (e.g. id). Only used when pagination=‘keyset’. |
page | integer | no | Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward. |
page_token | string | no | Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page. |
pagination | string | no | Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page. |
per_page | integer | no | Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large. |
sort | string (asc, desc) | no | Sort direction for keyset-paginated results: asc or desc. Only used when pagination=‘keyset’. |
storage_move.retrieve_all_project
Section titled “storage_move.retrieve_all_project”List all project repository storage moves on the instance. Returns: each move’s id, state, source and destination storage shards, and project. Admin-only and self-managed only. See also:
storage_move.get_project,storage_move.schedule_all_project.
- Meta-tool:
gitlab_storage_move, actionretrieve_all_project - Individual tool:
gitlab_retrieve_all_project_storage_moves - Tier: Free
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at instance (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
order_by | string | no | Column to order keyset-paginated results by (e.g. id). Only applies when pagination=‘keyset’. |
page | integer | no | Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward. |
page_token | string | no | Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page. |
pagination | string | no | Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page. |
per_page | integer | no | Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large. |
sort | string (asc, desc) | no | Sort direction for keyset-paginated results: asc or desc. Only applies when pagination=‘keyset’. |
storage_move.retrieve_all_snippet
Section titled “storage_move.retrieve_all_snippet”List every snippet repository storage move on the instance with ordering and pagination. Returns: storage moves with state, source and destination storage shards, the associated snippet, and pagination metadata. See also:
storage_move.get_snippet,storage_move.retrieve_snippet,storage_move.schedule_all_snippet.
- Meta-tool:
gitlab_storage_move, actionretrieve_all_snippet - Individual tool:
gitlab_retrieve_all_snippet_storage_moves - Tier: Free
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at instance (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
order_by | string | no | Field to order results by (for example ‘id’). Maps to the GitLab order_by query parameter. |
page | integer | no | Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward. |
page_token | string | no | Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page. |
pagination | string | no | Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page. |
per_page | integer | no | Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large. |
sort | string (asc, desc) | no | Sort direction: ‘asc’ or ‘desc’. Maps to the GitLab sort query parameter. |
storage_move.retrieve_group
Section titled “storage_move.retrieve_group”List repository storage moves for a single group. Returns: the group’s storage moves with state, source and destination storage names, creation time, and pagination metadata. See also:
storage_move.retrieve_all_group,storage_move.get_group_for_group,storage_move.schedule_group.
- Meta-tool:
gitlab_storage_move, actionretrieve_group - Individual tool:
gitlab_retrieve_group_storage_moves - Tier: Premium
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at group (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
group_id | integer | yes | Numeric ID of the group |
order_by | string | no | Column to order keyset-paginated results by (e.g. id). Only used when pagination=‘keyset’. |
page | integer | no | Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward. |
page_token | string | no | Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page. |
pagination | string | no | Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page. |
per_page | integer | no | Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large. |
sort | string (asc, desc) | no | Sort direction for keyset-paginated results: asc or desc. Only used when pagination=‘keyset’. |
storage_move.retrieve_project
Section titled “storage_move.retrieve_project”List repository storage moves for a single project. Returns: each move’s id, state, source and destination storage shards, and project. Admin-only and self-managed only. See also:
storage_move.get_project_for_project,storage_move.schedule_project.
- Meta-tool:
gitlab_storage_move, actionretrieve_project - Individual tool:
gitlab_retrieve_project_storage_moves - Tier: Free
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at project (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
project_id | integer | yes | Numeric ID of the project |
order_by | string | no | Column to order keyset-paginated results by (e.g. id). Only applies when pagination=‘keyset’. |
page | integer | no | Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward. |
page_token | string | no | Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page. |
pagination | string | no | Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page. |
per_page | integer | no | Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large. |
sort | string (asc, desc) | no | Sort direction for keyset-paginated results: asc or desc. Only applies when pagination=‘keyset’. |
storage_move.retrieve_snippet
Section titled “storage_move.retrieve_snippet”List repository storage moves for one snippet with ordering and pagination. Returns: storage moves scoped to the snippet with state, source and destination storage shards, and pagination metadata. See also:
storage_move.get_snippet_for_snippet,storage_move.retrieve_all_snippet,storage_move.schedule_snippet.
- Meta-tool:
gitlab_storage_move, actionretrieve_snippet - Individual tool:
gitlab_retrieve_snippet_storage_moves - Tier: Free
- Classic or OAuth token:
read_api(orapi); this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Read at instance (permissions page)
- Behavior: read-only, idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
snippet_id | integer | yes | Numeric ID of the snippet |
order_by | string | no | Field to order results by (for example ‘id’). Maps to the GitLab order_by query parameter. |
page | integer | no | Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward. |
page_token | string | no | Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page. |
pagination | string | no | Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page. |
per_page | integer | no | Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large. |
sort | string (asc, desc) | no | Sort direction: ‘asc’ or ‘desc’. Maps to the GitLab sort query parameter. |
storage_move.schedule_all_group
Section titled “storage_move.schedule_all_group”Schedule repository storage moves for all groups on a source storage shard. Returns: a confirmation that the bulk move has been scheduled. See also:
storage_move.retrieve_all_group,storage_move.schedule_group.
- Meta-tool:
gitlab_storage_move, actionschedule_all_group - Individual tool:
gitlab_schedule_all_group_storage_moves - Tier: Premium
- Classic or OAuth token:
api; this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Create at instance (permissions page)
- Behavior: writes, not idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
source_storage_name | string | yes | Name of the source storage shard |
destination_storage_name | string | no | Name of the destination storage shard |
storage_move.schedule_all_project
Section titled “storage_move.schedule_all_project”Schedule repository storage moves for all projects on a Gitaly storage shard. Drains source_storage_name onto destination_storage_name. Returns: a confirmation message. Admin-only and self-managed only. See also:
storage_move.retrieve_all_project,storage_move.schedule_project.
- Meta-tool:
gitlab_storage_move, actionschedule_all_project - Individual tool:
gitlab_schedule_all_project_storage_moves - Tier: Free
- Classic or OAuth token:
api; this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Create at instance (permissions page)
- Behavior: writes, not idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
source_storage_name | string | yes | Name of the source storage shard |
destination_storage_name | string | no | Name of the destination storage shard |
storage_move.schedule_all_snippet
Section titled “storage_move.schedule_all_snippet”Schedule repository storage moves for all snippets on a source Gitaly storage shard. Returns: a confirmation that the bulk move was scheduled. See also:
storage_move.retrieve_all_snippet,storage_move.schedule_snippet.
- Meta-tool:
gitlab_storage_move, actionschedule_all_snippet - Individual tool:
gitlab_schedule_all_snippet_storage_moves - Tier: Free
- Classic or OAuth token:
api; this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Create at instance (permissions page)
- Behavior: writes, not idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
source_storage_name | string | yes | Name of the source storage shard |
destination_storage_name | string | no | Name of the destination storage shard |
storage_move.schedule_group
Section titled “storage_move.schedule_group”Schedule a repository storage move for a single group. Returns: the scheduled storage move with state, source and destination storage names, and group reference. See also:
storage_move.retrieve_group,storage_move.get_group_for_group,storage_move.schedule_all_group.
- Meta-tool:
gitlab_storage_move, actionschedule_group - Individual tool:
gitlab_schedule_group_storage_move - Tier: Premium
- Classic or OAuth token:
api; this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Create at group (permissions page)
- Behavior: writes, not idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
group_id | integer | yes | Numeric ID of the group |
destination_storage_name | string | no | Name of the destination storage shard |
storage_move.schedule_project
Section titled “storage_move.schedule_project”Schedule a repository storage move for a single project to another Gitaly storage shard. Returns: the created move’s id, state, source and destination shards, and project. Admin-only and self-managed only. See also:
storage_move.retrieve_project,storage_move.schedule_all_project.
- Meta-tool:
gitlab_storage_move, actionschedule_project - Individual tool:
gitlab_schedule_project_storage_move - Tier: Free
- Classic or OAuth token:
api; this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Create at project (permissions page)
- Behavior: writes, not idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
project_id | integer | yes | Numeric ID of the project |
destination_storage_name | string | no | Name of the destination storage shard |
storage_move.schedule_snippet
Section titled “storage_move.schedule_snippet”Schedule a repository storage move for one snippet to a destination Gitaly storage shard. Returns: the scheduled storage move with its initial state and the associated snippet. See also:
storage_move.retrieve_snippet,storage_move.get_snippet_for_snippet,storage_move.schedule_all_snippet.
- Meta-tool:
gitlab_storage_move, actionschedule_snippet - Individual tool:
gitlab_schedule_snippet_storage_move - Tier: Free
- Classic or OAuth token:
api; this server lists the group only to a token that also carriesadmin_mode - Fine-grained token: Repository Storage Move: Create at instance (permissions page)
- Behavior: writes, not idempotent
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
snippet_id | integer | yes | Numeric ID of the snippet |
destination_storage_name | string | no | Name of the destination storage shard |