Releases

A release wraps a tag with its notes, milestones and downloadable assets. These actions list releases, read one or the latest, create one (for an existing tag or a new one from a ref), update and delete one, and manage the asset links of a release, one at a time or as a batch after a build. Deleting a release keeps its tag.

Sample questions

• “List the releases of project 42”
• “Create release v2.0.0 with the changelog as notes”
• “Attach the build artifacts to release v2.0.0”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as release.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_release 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_release_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 12, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 5 of the 12.

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
release.create	gitlab_release_create
release.delete	gitlab_release_delete
release.get	gitlab_release_get
release.get_latest	gitlab_release_latest
release.link_create	gitlab_release_link_create
release.link_create_batch	gitlab_release_link_create_batch
release.link_delete	gitlab_release_link_delete
release.link_get	gitlab_release_link_get
release.link_list	gitlab_release_link_list
release.link_update	gitlab_release_link_update
release.list	gitlab_release_list
release.update	gitlab_release_update

release.create

Create a release for a tag, optionally creating the tag from a ref and attaching asset links. Returns: the created release with author, commit, assets, milestones, and _links. See also: release.update, release.link_create, tag.create.

• Meta-tool: gitlab_release, action create
• Individual tool: gitlab_release_create
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Release: Create 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 associated with the release
assets	object	no	Asset links to attach to the release at creation time
description	string	no	Release notes (Markdown supported)
milestones	string[]	no	Milestone titles to associate with the release
name	string	no	Release title
ref	string	no	Branch or commit SHA to create tag from when tag_name does not exist. Include this when the prompt says ref/from ref
released_at	string	no	Date of the release in ISO 8601 format
tag_message	string	no	Message to use for the annotated tag (creates annotated tag instead of lightweight)

release.delete

Delete a release by tag_name (the Git tag itself is preserved). Returns: the deleted release details. See also: release.get, release.list, tag.delete.

• Meta-tool: gitlab_release, action delete
• Individual tool: gitlab_release_delete
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Release: 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	Tag name of the release to delete

release.get

Get a single release by project_id and tag_name. Returns: release notes, author, commit, assets, milestones, evidences, and _links. See also: release.list, release.update, release.delete, release.link_list.

• Meta-tool: gitlab_release, action get
• Individual tool: gitlab_release_get
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Release: 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 of the release

release.get_latest

Get the most recent release for a project. Returns: release notes, author, commit, assets, milestones, evidences, and _links. See also: release.list, release.get, release.create.

• Meta-tool: gitlab_release, action get_latest
• Individual tool: gitlab_release_latest
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Release: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path

release.link_create

Create a single release asset link. Returns: the created link with id, name, url, direct_asset_url, and link_type. See also: release.link_create_batch, release.link_list, release.link_update.

• Meta-tool: gitlab_release, action link_create
• Individual tool: gitlab_release_link_create
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Release Link: Create at project (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
name	string	yes	Name of the link
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name of the release
url	string	yes	Absolute http, https, or ftp URL of the link target. Do not use local file paths or relative paths.
direct_asset_path	string	no	Optional path for a direct asset link relative to the release: redirects to url. Use instead of the deprecated filepath.
filepath	string	no	Deprecated alias of direct_asset_path. Prefer direct_asset_path.
link_type	string (other, runbook, image, package)	no	Type of the release link: other, runbook, image, or package.

release.link_create_batch

Create multiple release asset links in one call. Returns: the created links (id, name, url, direct_asset_url, link_type) and any failed entries. See also: release.link_create, release.link_list, package.publish.

• Meta-tool: gitlab_release, action link_create_batch
• Individual tool: gitlab_release_link_create_batch
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Release Link: Create at project (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
links	object[]	yes	Array of release asset links. Each item supports name, url, link_type, direct_asset_path, and the deprecated filepath.
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name of the release

release.link_delete

Delete a release asset link by link_id. Returns: the deleted link with id, name, url, direct_asset_url, and link_type. See also: release.link_get, release.link_list.

• Meta-tool: gitlab_release, action link_delete
• Individual tool: gitlab_release_link_delete
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Release Link: Delete at project (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
link_id	integer	yes	ID of the release link to delete
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name of the release

release.link_get

Get one release asset link by link_id. Returns: the link with id, name, url, direct_asset_url, and link_type. See also: release.link_list, release.link_update, release.link_delete.

• Meta-tool: gitlab_release, action link_get
• Individual tool: gitlab_release_link_get
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Release Link: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
link_id	integer	yes	ID of the release link
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name of the release

release.link_list

List asset links for a release with offset or keyset pagination. Returns: matching links (id, name, url, direct_asset_url, link_type) and pagination metadata. See also: release.link_get, release.link_create, release.link_create_batch.

• Meta-tool: gitlab_release, action link_list
• Individual tool: gitlab_release_link_list
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Release Link: 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 of the release
order_by	string	no	Column to order keyset-paginated results by (e.g. created_at, updated_at)
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)

release.link_update

Update an existing release asset link by link_id. Returns: the updated link with id, name, url, direct_asset_url, and link_type. See also: release.link_get, release.link_list, release.link_delete.

• Meta-tool: gitlab_release, action link_update
• Individual tool: gitlab_release_link_update
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Release Link: Update at project (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
link_id	integer	yes	ID of the release link to update
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name of the release
direct_asset_path	string	no	New direct asset path for the link. Pass an empty string to remove it. Omit the field to leave it untouched
filepath	string	no	New filepath for a direct asset link. Pass an empty string to remove it. Omit the field to leave it untouched
link_type	string (other, runbook, image, package)	no	Type of the release link: other, runbook, image, or package.
name	string	no	New name of the link
url	string	no	Absolute http, https, or ftp URL of the link target. Do not use local file paths or relative paths.

Also needs at least one of: name; url.

release.list

List releases in a project with pagination. Returns: tag names, release names, release dates, and summary metadata. See also: release.get, tag.list, release.link_list.

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

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
include_html_description	boolean	no	Include the description_html field rendered from the Markdown description
order_by	string (released_at, created_at)	no	Order by field: released_at (default) or created_at
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)

release.update

Update an existing release’s title, notes, release date, or milestones. Returns: the updated release with author, commit, assets, milestones, and _links. See also: release.get, release.create, release.delete.

• Meta-tool: gitlab_release, action update
• Individual tool: gitlab_release_update
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Release: Update at project (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
tag_name	string	yes	Tag name of the release
description	string	no	Updated release notes
milestones	string[]	no	Milestone titles to associate with the release. Pass [] to detach every milestone. Omit the field to leave them untouched
name	string	no	New release title
released_at	string	no	New release date in ISO 8601 format