Tags

Tag management in one project: list, read, create and delete tags, read the GPG or X.509 signature of a tag, and protect tag patterns with the access level allowed to create them, then read or remove that protection. Deleting a tag also removes the release attached to it.

Sample questions

• “List the tags of project 42”
• “Create tag v2.0.0 on main”
• “Is tag v1.9.0 signed?”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as tag.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_tag 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_tag_create, with its parameters as the arguments.

Availability

Every tier serves the whole group, on self-managed instances and on GitLab.com alike.

Read-only actions: 5 of 9, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 5 of the 9.

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
tag.create	gitlab_tag_create
tag.delete	gitlab_tag_delete
tag.get	gitlab_tag_get
tag.get_protected	gitlab_tag_get_protected
tag.get_signature	gitlab_tag_get_signature
tag.list	gitlab_tag_list
tag.list_protected	gitlab_tag_list_protected
tag.protect	gitlab_tag_protect
tag.unprotect	gitlab_tag_unprotect

tag.create

Create a new tag in a project pointing at a ref. Returns: the created tag with target, message, protection flag, and the associated commit object. See also: tag.get, tag.delete, release.create.

• Meta-tool: gitlab_tag, action create
• Individual tool: gitlab_tag_create
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Repository Tag: Create at project (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
ref	string	yes	Commit SHA, branch name, or another tag to create the tag from
tag_name	string	yes	Name of the tag
message	string	no	Creates an annotated tag with this message

tag.delete

Delete a tag from a project permanently. Returns: a success confirmation naming the tag and project. See also: tag.get, tag.list, tag.unprotect.

• Meta-tool: gitlab_tag, action delete
• Individual tool: gitlab_tag_delete
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Repository Tag: Delete at project (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Name of the tag to delete

tag.get

Get a single tag from a project by name. Returns: the tag with target, message, protection flag, the full associated commit object, release note, and creation time. See also: tag.list, tag.get_signature, release.get.

• Meta-tool: gitlab_tag, action get
• Individual tool: gitlab_tag_get
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Repository Tag: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name to retrieve

tag.get_protected

Get a single protected tag or wildcard rule by name. Returns: the protected tag with its create access levels (access level, user, group, and deploy key descriptions). See also: tag.list_protected, tag.protect, tag.unprotect.

• Meta-tool: gitlab_tag, action get_protected
• Individual tool: gitlab_tag_get_protected
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Protected Tag: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Name of the protected tag

tag.get_signature

Get the X.509 signature of a tag. Returns: the signature type, verification status, and the X.509 certificate with issuer detail. See also: tag.get, tag.list.

• Meta-tool: gitlab_tag, action get_signature
• Individual tool: gitlab_tag_get_signature
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Repository Tag: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name to retrieve signature for

tag.list

List tags in one project with optional search and offset or keyset pagination. Returns: matching tags with target, message, protection flag, the associated commit object, release note, and pagination metadata. See also: tag.get, tag.create, release.list.

• Meta-tool: gitlab_tag, action list
• Individual tool: gitlab_tag_list
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Repository Tag: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
order_by	string (name, updated, version)	no	Order tags by name, updated (default), or version, which sorts by semantic version number
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.
search	string	no	Search query to filter tags by name
sort	string (asc, desc)	no	Sort direction (asc, desc)

tag.list_protected

List protected tags in one project with offset or keyset pagination. Returns: protected tag patterns with their create access levels and pagination metadata. See also: tag.get_protected, tag.protect, tag.list.

• Meta-tool: gitlab_tag, action list_protected
• Individual tool: gitlab_tag_list_protected
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Protected Tag: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
order_by	string	no	Column to order keyset-paginated results by
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)

tag.protect

Protect a tag or wildcard pattern with create access levels. Returns: the protected tag with its resolved create access levels. See also: tag.unprotect, tag.list_protected, tag.get_protected.

• Meta-tool: gitlab_tag, action protect
• Individual tool: gitlab_tag_protect
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Tag: Protect at project (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name or wildcard pattern (e.g. ‘v*’)
allowed_to_create	object[]	no	Granular create permissions (user_id, group_id, deploy_key_id, access_level)
create_access_level	integer	no	Access level allowed to create (0=No access, 30=Developer, 40=Maintainer)

tag.unprotect

Remove protection from a tag or wildcard pattern. Returns: a success confirmation naming the tag and project. See also: tag.protect, tag.list_protected, tag.get_protected.

• Meta-tool: gitlab_tag, action unprotect
• Individual tool: gitlab_tag_unprotect
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Tag: Protect at project (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Name of the protected tag to unprotect