Releases

Use this API to manage releases for a project, list the releases across a group, and manage the asset links attached to a release.

Asset links support the http, https, and ftp protocols.

List all releases in a group

GET /api/v4/groups/{id}/releases

Lists all releases for projects in a specified group.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the group owned by the authenticated user
`sort` Query	String	The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order Allowed values: `asc`, `desc` Default: `desc`
`simple` Query	Boolean	Return only limited fields for each release Default: `false`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesRelease
`400`	Bad request	—
`403`	Forbidden	—
`404`	Not found	—

List all releases in a project

GET /api/v4/projects/{id}/releases

Lists all releases for a specified project. Sorted by released_at.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`order_by` Query	String	The field to use as order. Either `released_at` (default) or `created_at` Allowed values: `released_at`, `created_at` Default: `released_at`
`sort` Query	String	The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order Allowed values: `asc`, `desc` Default: `desc`
`include_html_description` Query	Boolean	If `true`, a response includes HTML rendered markdown of the release description
`updated_before` Query	String (date-time)	Return releases updated before the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ
`updated_after` Query	String (date-time)	Return releases updated after the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ

Responses

Code	Description	Schema
`200`	OK	APIEntitiesRelease
`400`	Bad Request	—
`404`	Not Found	—

Create a release

POST /api/v4/projects/{id}/releases

Creates a release. Developer level access to the project is required to create a release.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`assets`	Object	Object that contains assets for the release
`assets.links`	Array of objects	Link information about the release
`assets.links[].direct_asset_path`	String	Optional path for a direct asset link
`assets.links[].filepath`	String	Deprecated: optional path for a direct asset link
`assets.links[].link_type`	String	The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`
`assets.links[].name` Required	String	The name of the link. Link names must be unique within the release
`assets.links[].url` Required	String	The URL of the link. Link URLs must be unique within the release
`description`	String	The description of the release. You can use Markdown
`legacy_catalog_publish`	Boolean	If true, the release will be published to the CI catalog. This parameter is for internal use only and will be removed in a future release. If the feature flag ci_release_cli_catalog_publish_option is disabled, this parameter will be ignored and the release will published to the CI catalog as it was before this parameter was introduced
`milestone_ids`	String or integer	The ID of each milestone the release is associated with. GitLab Premium customers can specify group milestones. Cannot be combined with `milestones` parameter. Mutually exclusive with `milestones`
`milestones`	Array of strings	The title of each milestone the release is associated with. GitLab Premium customers can specify group milestones. Cannot be combined with `milestone_ids` parameter. Mutually exclusive with `milestone_ids`
`name`	String	The release name
`ref`	String	If a tag specified in `tag_name` doesn’t exist, the release is created from `ref` and tagged with `tag_name`. It can be a commit SHA, another tag name, or a branch name
`released_at`	String (date-time)	Date and time for the release. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Only provide this field if creating an upcoming or historical release
`tag_message`	String	Message to use if creating a new annotated tag
`tag_name` Required	String	The tag where the release is created from

Responses

Code	Description	Schema
`201`	Created	APIEntitiesRelease
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`409`	Conflict	—
`422`	Unprocessable entity	—

Get the latest project release

GET /api/v4/projects/{id}/releases/permalink/latest

This feature was introduced in GitLab 15.4.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Get the latest project release

GET /api/v4/projects/{id}/releases/permalink/latest/{suffix_path}

This feature was introduced in GitLab 15.4.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`suffix_path` Path, required	String	The path to be suffixed to the latest release

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Retrieve a release by tag name

GET /api/v4/projects/{id}/releases/{tag_name}

Retrieves a release with a specified tag name.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The Git tag the release is associated with
`include_html_description` Query	Boolean	If `true`, a response includes HTML rendered markdown of the release description

Responses

Code	Description	Schema
`200`	OK	APIEntitiesRelease
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Update a release

PUT /api/v4/projects/{id}/releases/{tag_name}

Updates a release. Developer level access to the project is required to update a release.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The Git tag the release is associated with

Request body (application/json)

Property	Type	Description
`description`	String	The description of the release. You can use Markdown
`milestone_ids`	String or integer	The ID of each milestone the release is associated with. GitLab Premium customers can specify group milestones. Cannot be combined with `milestones` parameter. To remove all milestones from the release, specify `[]`. Mutually exclusive with `milestones`
`milestones`	Array of strings	The title of each milestone to associate with the release. GitLab Premium customers can specify group milestones. Cannot be combined with `milestone_ids` parameter. To remove all milestones from the release, specify `[]`. Mutually exclusive with `milestone_ids`
`name`	String	The release name
`released_at`	String (date-time)	The date when the release is/was ready. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`)

Responses

Code	Description	Schema
`200`	OK	APIEntitiesRelease
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Delete a release

DELETE /api/v4/projects/{id}/releases/{tag_name}

Delete a release. Deleting a release doesn’t delete the associated tag. Requires at least the Developer role for the project. This feature was introduced in GitLab 11.7.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The Git tag the release is associated with

Responses

Code	Description	Schema
`200`	OK	APIEntitiesRelease
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

List all release links

GET /api/v4/projects/{id}/releases/{tag_name}/assets/links

Lists all assets as links from a release.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The tag associated with the release
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesReleasesLink
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Create a release link

POST /api/v4/projects/{id}/releases/{tag_name}/assets/links

Creates an asset link for a specified release.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The tag associated with the release

Request body (application/json)

Property	Type	Description
`direct_asset_path`	String	Optional path for a direct asset link
`filepath`	String	Deprecated: optional path for a direct asset link
`link_type`	String	The type of the link: `other`, `runbook`, `image`, or `package`. Defaults to `other` Allowed values: `other`, `runbook`, `image`, `package` Default: `other`
`name` Required	String	The name of the link. Link names must be unique in the release
`url` Required	String	The URL of the link. Link URLs must be unique in the release

Responses

Code	Description	Schema
`201`	Created	APIEntitiesReleasesLink
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not Found	—

Retrieve a release link

GET /api/v4/projects/{id}/releases/{tag_name}/assets/links/{link_id}

Retrieves a specified asset as a link from a release.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The tag associated with the release
`link_id` Path, required	Integer	The ID of the link

Responses

Code	Description	Schema
`200`	OK	APIEntitiesReleasesLink
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Update a release link

PUT /api/v4/projects/{id}/releases/{tag_name}/assets/links/{link_id}

Updates a specified asset link for a release.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The tag associated with the release
`link_id` Path, required	Integer	The ID of the link

Request body (application/json)

Property	Type	Description
`direct_asset_path`	String	Optional path for a direct asset link
`filepath`	String	Deprecated: optional path for a direct asset link
`link_type`	String	The type of the link: `other`, `runbook`, `image`, or `package`. Defaults to `other` Allowed values: `other`, `runbook`, `image`, `package` Default: `other`
`name`	String	The name of the link
`url`	String	The URL of the link

Responses

Code	Description	Schema
`200`	OK	APIEntitiesReleasesLink
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not Found	—

Delete a release link

DELETE /api/v4/projects/{id}/releases/{tag_name}/assets/links/{link_id}

Deletes a specified asset link from a release.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The tag associated with the release
`link_id` Path, required	Integer	The ID of the link

Responses

Code	Description	Schema
`200`	OK	APIEntitiesReleasesLink
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not Found	—

Download a project release asset file

GET /api/v4/projects/{id}/releases/{tag_name}/downloads/{direct_asset_path}

This feature was introduced in GitLab 15.4.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The Git tag the release is associated with
`direct_asset_path` Path, required	String	The path to the file to download, as specified when creating the release asset

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCommit

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`created_at`	String (date-time)	Example: `2017-07-26T11:08:53.000+02:00`
`extended_trailers`	Object	Example: `{"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`
`short_id`	String	Example: `2695effb`
`title`	String	Example: `Initial commit`
`trailers`	Object	Example: `{"Merged-By":"Jane Doe janedoe@gitlab.com"}`
`web_url`	String	Example: `https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746`

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesMilestoneWithStats

Property	Type	Description
`created_at`	String	—
`description`	String	—
`due_date`	String	—
`expired`	Boolean	—
`group_id`	String	—
`id`	Integer (int64)	—
`iid`	Integer (int64)	—
`issue_stats`	Object	—
`issue_stats.closed`	Integer	Example: `5`
`issue_stats.total`	Integer	Example: `10`
`project_id`	Integer (int64)	—
`start_date`	String	—
`state`	String	—
`title`	String	—
`updated_at`	String	—
`web_url`	String	—

APIEntitiesRelease

Property	Type	Description
`_links`	Object	—
`_links.closed_issues_url`	String	—
`_links.closed_merge_requests_url`	String	—
`_links.edit_url`	String	—
`_links.merged_merge_requests_url`	String	—
`_links.opened_issues_url`	String	—
`_links.opened_merge_requests_url`	String	—
`_links.self`	String	—
`assets`	Object	—
`assets.count`	Integer	Example: `2`
`assets.links`	APIEntitiesReleasesLink	—
`assets.sources`	APIEntitiesReleasesSource	—
`author`	APIEntitiesUserBasic	—
`commit`	APIEntitiesCommit	—
`commit_path`	String	Example: `/root/app/commit/588440f66559714280628a4f9799f0c4eb880a4a`
`created_at`	String (date-time)	Example: `2019-01-03T01:56:19.539Z`
`description`	String	Example: `Finally released v1.0`
`description_html`	String	—
`evidences`	APIEntitiesReleasesEvidence	—
`milestones`	APIEntitiesMilestoneWithStats	—
`name`	String	Example: `Release v1.0`
`released_at`	String (date-time)	Example: `2019-01-03T01:56:19.539Z`
`tag_name`	String	Example: `v1.0`
`tag_path`	String	Example: `/root/app/-/tags/v1.0`
`upcoming_release`	Boolean	—

APIEntitiesReleasesEvidence

Property	Type	Description
`collected_at`	String (date-time)	Example: `2019-01-03T01:56:19.539Z`
`filepath`	String	Example: `https://gitlab.example.com/root/app/-/releases/v1.0/evidence.json`
`sha`	String	Example: `760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d`

APIEntitiesReleasesLink

Property	Type	Description
`direct_asset_url`	String	Example: `https://gitlab.example.com/root/app/-/releases/v1.0/downloads/app-v1.0.dmg`
`id`	Integer (int64)	Example: `1`
`link_type`	String	Example: `other`
`name`	String	Example: `app-v1.0.dmg`
`url`	String	Example: `https://gitlab.example.com/root/app/-/jobs/688/artifacts/raw/bin/app-v1.0.dmg`

APIEntitiesReleasesSource

Property	Type	Description
`format`	String	Example: `zip`
`url`	String	Example: `https://gitlab.example.com/root/app/-/archive/v1.0/app-v1.0.zip`

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

List all releases in a group

List all releases in a project

Create a release

Get the latest project release

Get the latest project release

Retrieve a release by tag name

Update a release

Delete a release

List all release links

Create a release link

Retrieve a release link

Update a release link

Delete a release link

Download a project release asset file

Schemas

APIEntitiesCommit

APIEntitiesCustomAttribute

APIEntitiesMilestoneWithStats

APIEntitiesRelease

APIEntitiesReleasesEvidence

APIEntitiesReleasesLink

APIEntitiesReleasesSource

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error