Geo sites

Geo replicates a GitLab instance to other sites. These actions manage the sites (list, read, create, edit and delete), repair a site’s OAuth application, and read the replication status of one site or of all of them. They are administrator actions.

Sample questions

• “List the Geo sites”
• “What is the replication status of Geo site 2?”
• “Repair the OAuth application of the secondary site”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as geo.create, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_geo with action set to the action’s name, such as create, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_create_geo_site, with its parameters as the arguments.

Availability

How many of these actions an instance serves at each tier, out of a total of 8:

• Free: 0
• Premium: 8
• Ultimate: 8

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: 4 of 8, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 4 of the 8.

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. A destructive action runs only once confirmed, unless GITLAB_MCP_YOLO_MODE (or AUTOPILOT) skips that step: the dynamic surface needs confirm: true on gitlab_execute_action, and the other two take a confirm parameter or the client’s prompt (Destructive actions).

Action	Individual
geo.create	gitlab_create_geo_site
geo.delete	gitlab_delete_geo_site
geo.edit	gitlab_edit_geo_site
geo.get	gitlab_get_geo_site
geo.get_status	gitlab_get_status_geo_site
geo.list	gitlab_list_geo_sites
geo.list_status	gitlab_list_status_all_geo_sites
geo.repair	gitlab_repair_geo_site

geo.create

Create a new Geo site. Returns: the site with id, name, url, primary/enabled flags, capacities, selective-sync settings, and navigation links. See also: geo.list, geo.get, geo.edit.

• Meta-tool: gitlab_geo, action create
• Individual tool: gitlab_create_geo_site
• Tier: Premium
• Classic or OAuth token: api; this server lists the group only to a token that also carries admin_mode
• Fine-grained token: Geo Site: Create at instance (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
name	string	yes	Unique name of the Geo site
url	string	yes	External URL of the Geo site
container_repositories_max_capacity	integer	no	Max number of concurrent container repository syncs
enabled	boolean	no	Whether the site is enabled
files_max_capacity	integer	no	Max number of LFS/attachment backfill downloads
internal_url	string	no	Internal URL of the Geo site
minimum_reverification_interval	integer	no	Minimum interval (days) before re-verification
primary	boolean	no	Whether this is a primary site
repos_max_capacity	integer	no	Max number of concurrent repository backfill syncs
selective_sync_namespace_ids	integer[]	no	Namespace IDs to sync (when selective_sync_type=namespaces)
selective_sync_shards	string[]	no	Storage shards to sync (when selective_sync_type=shards)
selective_sync_type	string	no	Selective sync type: namespaces or shards
sync_object_storage	boolean	no	Whether to sync object-stored data
verification_max_capacity	integer	no	Max number of concurrent verification jobs

geo.delete

Delete a Geo site permanently. Returns: a success confirmation naming the site. See also: geo.get, geo.list.

• Meta-tool: gitlab_geo, action delete
• Individual tool: gitlab_delete_geo_site
• Tier: Premium
• Classic or OAuth token: api; this server lists the group only to a token that also carries admin_mode
• Fine-grained token: Geo Site: Delete at instance (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
id	integer	yes	Numeric ID of the Geo site

geo.edit

Edit a Geo site’s settings. Returns: the updated site with its capacities and selective-sync configuration. See also: geo.get, geo.list, geo.repair.

• Meta-tool: gitlab_geo, action edit
• Individual tool: gitlab_edit_geo_site
• Tier: Premium
• Classic or OAuth token: api; this server lists the group only to a token that also carries admin_mode
• Fine-grained token: Geo Site: Update at instance (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
id	integer	yes	Numeric ID of the Geo site
container_repositories_max_capacity	integer	no	Max number of concurrent container repository syncs
enabled	boolean	no	Whether the site is enabled
files_max_capacity	integer	no	Max number of LFS/attachment backfill downloads
internal_url	string	no	Internal URL of the Geo site
minimum_reverification_interval	integer	no	Minimum interval (days) before re-verification
name	string	no	Unique name of the Geo site
repos_max_capacity	integer	no	Max number of concurrent repository backfill syncs
selective_sync_namespace_ids	integer[]	no	Namespace IDs to sync
selective_sync_shards	string[]	no	Storage shards to sync
selective_sync_type	string	no	Selective sync type: namespaces or shards
url	string	no	External URL of the Geo site
verification_max_capacity	integer	no	Max number of concurrent verification jobs

geo.get

Get a single Geo site by id. Returns: the site with name, url, primary/enabled flags, capacities, selective-sync settings, and navigation links. See also: geo.list, geo.edit, geo.get_status.

• Meta-tool: gitlab_geo, action get
• Individual tool: gitlab_get_geo_site
• Tier: Premium
• Classic or OAuth token: read_api (or api); this server lists the group only to a token that also carries admin_mode
• Fine-grained token: Geo Site: Read at instance (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
id	integer	yes	Numeric ID of the Geo site

geo.get_status

Get replication status for one Geo site. Returns: health, replication lag, and detailed sync/verification/checksum counts and percentages plus navigation links. See also: geo.list_status, geo.get.

• Meta-tool: gitlab_geo, action get_status
• Individual tool: gitlab_get_status_geo_site
• Tier: Premium
• Classic or OAuth token: read_api (or api); this server lists the group only to a token that also carries admin_mode
• Fine-grained token: Geo Site: Read at instance (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
id	integer	yes	Numeric ID of the Geo site

geo.list

List all Geo sites. Returns: each site with id, name, url, primary/enabled flags, capacities, and pagination metadata. See also: geo.get, geo.list_status, geo.create.

• Meta-tool: gitlab_geo, action list
• Individual tool: gitlab_list_geo_sites
• Tier: Premium
• Classic or OAuth token: read_api (or api); this server lists the group only to a token that also carries admin_mode
• Fine-grained token: Geo Site: Read at instance (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
order_by	string	no	Column to order results by (keyset pagination)
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, desc)

geo.list_status

List replication status for all Geo sites. Returns: per-site health, replication lag, and detailed sync/verification/checksum counts and percentages, with pagination metadata. See also: geo.get_status, geo.list.

• Meta-tool: gitlab_geo, action list_status
• Individual tool: gitlab_list_status_all_geo_sites
• Tier: Premium
• Classic or OAuth token: read_api (or api); this server lists the group only to a token that also carries admin_mode
• Fine-grained token: Geo Site: Read at instance (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
order_by	string	no	Column to order results by (keyset pagination)
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, desc)

geo.repair

Repair a Geo site’s OAuth application. Returns: the repaired site (or a hint to refresh via get when GitLab returns no body). See also: geo.get, geo.get_status.

• Meta-tool: gitlab_geo, action repair
• Individual tool: gitlab_repair_geo_site
• Tier: Premium
• Classic or OAuth token: api; this server lists the group only to a token that also carries admin_mode
• Fine-grained token: Geo Site: Repair at instance (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
id	integer	yes	Numeric ID of the Geo site