2020-06-16 23:08:38 -04:00
---
stage: Release
2020-12-01 10:09:28 -05:00
group: Release
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-16 23:08:38 -04:00
---
2019-01-04 09:28:40 -05:00
# Releases API
2020-05-21 02:08:25 -04:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7.
2020-12-15 19:09:58 -05:00
> - Using this API you can manipulate GitLab [Release](../../user/project/releases/index.md) entries.
2019-02-15 04:39:23 -05:00
> - For manipulating links as a release asset, see [Release Links API](links.md).
2020-05-21 02:08:25 -04:00
> - Release Evidences were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.5.
2021-06-03 08:10:18 -04:00
> - `description_html` became an opt-in field [with GitLab 13.12 for performance reasons](https://gitlab.com/gitlab-org/gitlab/-/issues/299447).
Please pass the `include_html_description` query string parameter if you need it.
2021-07-06 23:08:47 -04:00
> - [The permission model for create, update and delete actions was fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/327505) in GitLab 14.1.
See [Release permissions ](../../user/project/releases/index.md#release-permissions ) for more information.
2019-01-04 09:28:40 -05:00
2021-07-20 23:09:46 -04:00
## Authentication
For authentication, the Releases API accepts either:
- A [Personal Access Token ](../../user/profile/personal_access_tokens.md ) using the
`PRIVATE-TOKEN` header.
2021-09-03 14:10:36 -04:00
- The [GitLab CI/CD job token ](../../ci/jobs/ci_job_token.md ) `$CI_JOB_TOKEN` using
2021-07-20 23:09:46 -04:00
the `JOB-TOKEN` header.
2019-01-04 09:28:40 -05:00
## List Releases
2019-07-16 07:47:46 -04:00
Paginated list of Releases, sorted by `released_at` .
2019-01-04 09:28:40 -05:00
2020-02-27 22:09:04 -05:00
```plaintext
2019-01-04 09:28:40 -05:00
GET /projects/:id/releases
```
2019-09-01 19:45:31 -04:00
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../index.md#namespaced-path-encoding ). |
2020-10-12 14:08:31 -04:00
| `order_by` | string | no | The field to use as order. Either `released_at` (default) or `created_at` . |
| `sort` | string | no | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. |
2021-06-03 08:10:18 -04:00
| `include_html_description` | boolean | no | If `true` , a response includes HTML rendered Markdown of the release description. |
2019-01-04 09:28:40 -05:00
Example request:
2020-01-30 10:09:15 -05:00
```shell
2021-01-11 01:10:29 -05:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases"
2019-01-04 09:28:40 -05:00
```
Example response:
```json
[
{
"tag_name":"v0.2",
"description":"## CHANGELOG\r\n\r\n- Escape label and milestone titles to prevent XSS in GFM autocomplete. !2740\r\n- Prevent private snippets from being embeddable.\r\n- Add subresources removal to member destroy service.",
"name":"Awesome app v0.2 beta",
"created_at":"2019-01-03T01:56:19.539Z",
2019-07-16 07:47:46 -04:00
"released_at":"2019-01-03T01:56:19.539Z",
2019-01-04 09:28:40 -05:00
"author":{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
2019-09-01 19:45:31 -04:00
"web_url":"https://gitlab.example.com/root"
2019-01-04 09:28:40 -05:00
},
"commit":{
"id":"079e90101242458910cccd35eab0e211dfc359c0",
"short_id":"079e9010",
"title":"Update README.md",
"created_at":"2019-01-03T01:55:38.000Z",
"parent_ids":[
"f8d3d94cbd347e924aa7b715845e439d00e80ca4"
],
"message":"Update README.md",
"author_name":"Administrator",
"author_email":"admin@example.com",
"authored_date":"2019-01-03T01:55:38.000Z",
"committer_name":"Administrator",
"committer_email":"admin@example.com",
"committed_date":"2019-01-03T01:55:38.000Z"
},
2019-09-16 11:06:26 -04:00
"milestones": [
{
"id":51,
"iid":1,
"project_id":24,
"title":"v1.0-rc",
"description":"Voluptate fugiat possimus quis quod aliquam expedita.",
"state":"closed",
"created_at":"2019-07-12T19:45:44.256Z",
"updated_at":"2019-07-12T19:45:44.256Z",
2021-09-06 14:11:17 -04:00
"due_date":"2019-08-16",
"start_date":"2019-07-30",
2020-03-11 14:09:23 -04:00
"web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1",
"issue_stats": {
"total": 98,
"closed": 76
}
2019-09-16 11:06:26 -04:00
},
{
"id":52,
"iid":2,
"project_id":24,
"title":"v1.0",
"description":"Voluptate fugiat possimus quis quod aliquam expedita.",
"state":"closed",
"created_at":"2019-07-16T14:00:12.256Z",
"updated_at":"2019-07-16T14:00:12.256Z",
2021-09-06 14:11:17 -04:00
"due_date":"2019-08-16",
"start_date":"2019-07-30",
2020-03-11 14:09:23 -04:00
"web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2",
"issue_stats": {
"total": 24,
"closed": 21
}
2019-09-16 11:06:26 -04:00
}
],
2019-09-23 14:06:14 -04:00
"commit_path":"/root/awesome-app/commit/588440f66559714280628a4f9799f0c4eb880a4a",
"tag_path":"/root/awesome-app/-/tags/v0.11.1",
2019-01-04 09:28:40 -05:00
"assets":{
"count":6,
"sources":[
{
"format":"zip",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.zip"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.gz",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar.gz"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.bz2",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar.bz2"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar"
2019-01-04 09:28:40 -05:00
}
],
"links":[
{
"id":2,
"name":"awesome-v0.2.msi",
"url":"http://192.168.10.15:3000/msi",
2020-06-03 14:08:28 -04:00
"external":true,
"link_type":"other"
2019-01-04 09:28:40 -05:00
},
{
"id":1,
"name":"awesome-v0.2.dmg",
"url":"http://192.168.10.15:3000",
2020-06-03 14:08:28 -04:00
"external":true,
"link_type":"other"
2019-01-04 09:28:40 -05:00
}
2019-11-19 04:06:16 -05:00
],
"evidence_file_path":"https://gitlab.example.com/root/awesome-app/-/releases/v0.2/evidence.json"
2019-10-14 17:06:30 -04:00
},
2020-05-15 14:07:52 -04:00
"evidences":[
{
2021-04-29 08:09:58 -04:00
"sha": "760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d",
"filepath": "https://gitlab.example.com/root/awesome-app/-/releases/v0.2/evidence.json",
"collected_at": "2019-01-03T01:56:19.539Z"
2020-05-15 14:07:52 -04:00
}
]
2019-01-04 09:28:40 -05:00
},
{
"tag_name":"v0.1",
"description":"## CHANGELOG\r\n\r\n-Remove limit of 100 when searching repository code. !8671\r\n- Show error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\r\n- Fix a bug where internal email pattern wasn't respected. !22516",
"name":"Awesome app v0.1 alpha",
"created_at":"2019-01-03T01:55:18.203Z",
2019-07-16 07:47:46 -04:00
"released_at":"2019-01-03T01:55:18.203Z",
2019-01-04 09:28:40 -05:00
"author":{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
2019-09-01 19:45:31 -04:00
"web_url":"https://gitlab.example.com/root"
2019-01-04 09:28:40 -05:00
},
"commit":{
"id":"f8d3d94cbd347e924aa7b715845e439d00e80ca4",
"short_id":"f8d3d94c",
"title":"Initial commit",
"created_at":"2019-01-03T01:53:28.000Z",
"parent_ids":[
],
"message":"Initial commit",
"author_name":"Administrator",
"author_email":"admin@example.com",
"authored_date":"2019-01-03T01:53:28.000Z",
"committer_name":"Administrator",
"committer_email":"admin@example.com",
"committed_date":"2019-01-03T01:53:28.000Z"
},
"assets":{
"count":4,
"sources":[
{
"format":"zip",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.gz",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.bz2",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar"
2019-01-04 09:28:40 -05:00
}
],
"links":[
2019-11-19 04:06:16 -05:00
],
"evidence_file_path":"https://gitlab.example.com/root/awesome-app/-/releases/v0.1/evidence.json"
2019-10-14 17:06:30 -04:00
},
2020-05-15 14:07:52 -04:00
"evidences":[
{
2021-04-29 08:09:58 -04:00
"sha": "c3ffedec13af470e760d6cdfb08790f71cf52c6cde4d",
"filepath": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/evidence.json",
"collected_at": "2019-01-03T01:55:18.203Z"
2020-05-15 14:07:52 -04:00
}
]
2019-01-04 09:28:40 -05:00
}
]
```
## Get a Release by a tag name
Get a Release for the given tag.
2020-02-27 22:09:04 -05:00
```plaintext
2019-01-04 09:28:40 -05:00
GET /projects/:id/releases/:tag_name
```
2019-09-01 19:45:31 -04:00
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../index.md#namespaced-path-encoding ). |
2020-11-09 13:09:11 -05:00
| `tag_name` | string | yes | The Git tag the release is associated with. |
2021-06-03 08:10:18 -04:00
| `include_html_description` | boolean | no | If `true` , a response includes HTML rendered Markdown of the release description. |
2019-01-04 09:28:40 -05:00
Example request:
2020-01-30 10:09:15 -05:00
```shell
2021-01-11 01:10:29 -05:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases/v0.1"
2019-01-04 09:28:40 -05:00
```
Example response:
```json
{
"tag_name":"v0.1",
"description":"## CHANGELOG\r\n\r\n- Remove limit of 100 when searching repository code. !8671\r\n- Show error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\r\n- Fix a bug where internal email pattern wasn't respected. !22516",
"name":"Awesome app v0.1 alpha",
"created_at":"2019-01-03T01:55:18.203Z",
2019-07-16 07:47:46 -04:00
"released_at":"2019-01-03T01:55:18.203Z",
2019-01-04 09:28:40 -05:00
"author":{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
2019-09-01 19:45:31 -04:00
"web_url":"https://gitlab.example.com/root"
2019-01-04 09:28:40 -05:00
},
"commit":{
"id":"f8d3d94cbd347e924aa7b715845e439d00e80ca4",
"short_id":"f8d3d94c",
"title":"Initial commit",
"created_at":"2019-01-03T01:53:28.000Z",
"parent_ids":[
],
"message":"Initial commit",
"author_name":"Administrator",
"author_email":"admin@example.com",
"authored_date":"2019-01-03T01:53:28.000Z",
"committer_name":"Administrator",
"committer_email":"admin@example.com",
"committed_date":"2019-01-03T01:53:28.000Z"
},
2019-09-16 11:06:26 -04:00
"milestones": [
{
"id":51,
"iid":1,
"project_id":24,
"title":"v1.0-rc",
"description":"Voluptate fugiat possimus quis quod aliquam expedita.",
"state":"closed",
"created_at":"2019-07-12T19:45:44.256Z",
"updated_at":"2019-07-12T19:45:44.256Z",
2021-09-06 14:11:17 -04:00
"due_date":"2019-08-16",
"start_date":"2019-07-30",
2020-03-11 14:09:23 -04:00
"web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1",
"issue_stats": {
"total": 98,
"closed": 76
}
2019-09-16 11:06:26 -04:00
},
{
"id":52,
"iid":2,
"project_id":24,
"title":"v1.0",
"description":"Voluptate fugiat possimus quis quod aliquam expedita.",
"state":"closed",
"created_at":"2019-07-16T14:00:12.256Z",
"updated_at":"2019-07-16T14:00:12.256Z",
2021-09-06 14:11:17 -04:00
"due_date":"2019-08-16",
"start_date":"2019-07-30",
2020-03-11 14:09:23 -04:00
"web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2",
"issue_stats": {
"total": 24,
"closed": 21
}
2019-09-16 11:06:26 -04:00
}
],
2019-09-23 14:06:14 -04:00
"commit_path":"/root/awesome-app/commit/588440f66559714280628a4f9799f0c4eb880a4a",
"tag_path":"/root/awesome-app/-/tags/v0.11.1",
2019-01-04 09:28:40 -05:00
"assets":{
2019-11-19 04:06:16 -05:00
"count":5,
2019-01-04 09:28:40 -05:00
"sources":[
{
"format":"zip",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.gz",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.bz2",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar"
2019-01-04 09:28:40 -05:00
}
],
"links":[
2020-03-16 11:09:27 -04:00
{
"id":3,
"name":"hoge",
"url":"https://gitlab.example.com/root/awesome-app/-/tags/v0.11.1/binaries/linux-amd64",
2020-06-03 14:08:28 -04:00
"external":true,
"link_type":"other"
2020-03-16 11:09:27 -04:00
}
2020-05-04 17:09:41 -04:00
]
2019-10-14 17:06:30 -04:00
},
2020-05-04 17:09:41 -04:00
"evidences":[
{
2021-04-29 08:09:58 -04:00
"sha": "760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d",
"filepath": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/evidence.json",
"collected_at": "2019-07-16T14:00:12.256Z"
2020-05-04 17:09:41 -04:00
}
]
2019-01-04 09:28:40 -05:00
}
```
## Create a release
2021-03-01 19:11:26 -05:00
Create a release. Developer level access to the project is required to create a release.
2019-01-04 09:28:40 -05:00
2020-02-27 22:09:04 -05:00
```plaintext
2019-01-04 09:28:40 -05:00
POST /projects/:id/releases
```
2019-10-07 14:06:24 -04:00
| Attribute | Type | Required | Description |
| -------------------| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../index.md#namespaced-path-encoding ). |
2019-11-12 16:06:30 -05:00
| `name` | string | no | The release name. |
2020-12-17 16:09:57 -05:00
| `tag_name` | string | yes | The tag where the release is created from. |
2020-03-16 08:09:12 -04:00
| `description` | string | no | The description of the release. You can use [Markdown ](../../user/markdown.md ). |
2020-12-17 16:09:57 -05:00
| `ref` | string | yes, if `tag_name` doesn't exist | 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. |
2020-10-07 17:08:21 -04:00
| `milestones` | array of string | no | The title of each milestone the release is associated with. [GitLab Premium ](https://about.gitlab.com/pricing/ ) customers can specify group milestones. |
2019-10-07 14:06:24 -04:00
| `assets:links` | array of hash | no | An array of assets links. |
2020-11-26 01:09:20 -05:00
| `assets:links:name` | string | required by: `assets:links` | The name of the link. Link names must be unique within the release. |
| `assets:links:url` | string | required by: `assets:links` | The URL of the link. Link URLs must be unique within the release. |
2020-11-06 13:09:07 -05:00
| `assets:links:filepath` | string | no | Optional path for a [Direct Asset link ](../../user/project/releases/index.md#permanent-links-to-release-assets ).
2020-06-03 14:08:28 -04:00
| `assets:links:link_type` | string | no | The type of the link: `other` , `runbook` , `image` , `package` . Defaults to `other` .
2020-12-17 16:09:57 -05:00
| `released_at` | datetime | no | The date when the release is/was ready. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
2019-01-04 09:28:40 -05:00
Example request:
2020-01-30 10:09:15 -05:00
```shell
2021-01-11 01:10:29 -05:00
curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: < your_access_token > " \
2020-06-03 14:08:28 -04:00
--data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "milestones": ["v1.0", "v1.0-rc"], "assets": { "links": [{ "name": "hoge", "url": "https://google.com", "filepath": "/binaries/linux-amd64", "link_type":"other" }] } }' \
2020-12-08 04:09:41 -05:00
--request POST "https://gitlab.example.com/api/v4/projects/24/releases"
2019-01-04 09:28:40 -05:00
```
Example response:
```json
{
"tag_name":"v0.3",
"description":"Super nice release",
"name":"New release",
"created_at":"2019-01-03T02:22:45.118Z",
2019-07-16 07:47:46 -04:00
"released_at":"2019-01-03T02:22:45.118Z",
2019-01-04 09:28:40 -05:00
"author":{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
2019-09-01 19:45:31 -04:00
"web_url":"https://gitlab.example.com/root"
2019-01-04 09:28:40 -05:00
},
"commit":{
"id":"079e90101242458910cccd35eab0e211dfc359c0",
"short_id":"079e9010",
"title":"Update README.md",
"created_at":"2019-01-03T01:55:38.000Z",
"parent_ids":[
"f8d3d94cbd347e924aa7b715845e439d00e80ca4"
],
"message":"Update README.md",
"author_name":"Administrator",
"author_email":"admin@example.com",
"authored_date":"2019-01-03T01:55:38.000Z",
"committer_name":"Administrator",
"committer_email":"admin@example.com",
"committed_date":"2019-01-03T01:55:38.000Z"
},
2019-09-16 11:06:26 -04:00
"milestones": [
{
"id":51,
"iid":1,
"project_id":24,
"title":"v1.0-rc",
"description":"Voluptate fugiat possimus quis quod aliquam expedita.",
"state":"closed",
"created_at":"2019-07-12T19:45:44.256Z",
"updated_at":"2019-07-12T19:45:44.256Z",
2021-09-06 14:11:17 -04:00
"due_date":"2019-08-16",
"start_date":"2019-07-30",
2020-03-11 14:09:23 -04:00
"web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1",
"issue_stats": {
"total": 99,
"closed": 76
}
2019-09-16 11:06:26 -04:00
},
{
"id":52,
"iid":2,
"project_id":24,
"title":"v1.0",
"description":"Voluptate fugiat possimus quis quod aliquam expedita.",
"state":"closed",
"created_at":"2019-07-16T14:00:12.256Z",
"updated_at":"2019-07-16T14:00:12.256Z",
2021-09-06 14:11:17 -04:00
"due_date":"2019-08-16",
"start_date":"2019-07-30",
2020-03-11 14:09:23 -04:00
"web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2",
"issue_stats": {
"total": 24,
"closed": 21
}
2019-09-16 11:06:26 -04:00
}
],
2019-09-23 14:06:14 -04:00
"commit_path":"/root/awesome-app/commit/588440f66559714280628a4f9799f0c4eb880a4a",
"tag_path":"/root/awesome-app/-/tags/v0.11.1",
2019-11-19 04:06:16 -05:00
"evidence_sha":"760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d",
2019-01-04 09:28:40 -05:00
"assets":{
"count":5,
"sources":[
{
"format":"zip",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.zip"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.gz",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar.gz"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.bz2",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar.bz2"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar"
2019-01-04 09:28:40 -05:00
}
],
"links":[
{
"id":3,
"name":"hoge",
2020-03-16 11:09:27 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/tags/v0.11.1/binaries/linux-amd64",
2020-06-03 14:08:28 -04:00
"external":true,
"link_type":"other"
2019-01-04 09:28:40 -05:00
}
2019-11-19 04:06:16 -05:00
],
"evidence_file_path":"https://gitlab.example.com/root/awesome-app/-/releases/v0.3/evidence.json"
2021-04-29 08:09:58 -04:00
}
2019-01-04 09:28:40 -05:00
}
```
2021-01-28 07:09:54 -05:00
### Group milestones **(PREMIUM SELF)**
2020-10-07 17:08:21 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235391) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5.
Group milestones associated with the project may be specified in the `milestones`
array for [Create a release ](#create-a-release ) and [Update a release ](#update-a-release )
API calls. Only milestones associated with the project's group may be specified, and
2020-12-17 16:09:57 -05:00
adding milestones for ancestor groups raises an error.
2020-10-07 17:08:21 -04:00
2021-01-28 07:09:54 -05:00
## Collect release evidence **(PREMIUM SELF)**
2020-03-31 08:08:09 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10.
Create Evidence for an existing Release.
```plaintext
POST /projects/:id/releases/:tag_name/evidence
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../index.md#namespaced-path-encoding ). |
2020-11-09 13:09:11 -05:00
| `tag_name` | string | yes | The Git tag the release is associated with. |
2020-03-31 08:08:09 -04:00
Example request:
```shell
2021-01-11 01:10:29 -05:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/evidence"
2020-03-31 08:08:09 -04:00
```
Example response:
```json
200
```
2019-01-04 09:28:40 -05:00
## Update a release
2021-03-01 19:11:26 -05:00
Update a release. Developer level access to the project is required to update a release.
2019-01-04 09:28:40 -05:00
2020-02-27 22:09:04 -05:00
```plaintext
2019-01-04 09:28:40 -05:00
PUT /projects/:id/releases/:tag_name
```
2019-09-16 11:06:26 -04:00
| Attribute | Type | Required | Description |
| ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../index.md#namespaced-path-encoding ). |
2020-11-09 13:09:11 -05:00
| `tag_name` | string | yes | The Git tag the release is associated with. |
2019-09-16 11:06:26 -04:00
| `name` | string | no | The release name. |
2019-11-27 22:06:32 -05:00
| `description` | string | no | The description of the release. You can use [Markdown ](../../user/markdown.md ). |
2020-10-07 17:08:21 -04:00
| `milestones` | array of string | no | The title of each milestone to associate with the release. [GitLab Premium ](https://about.gitlab.com/pricing/ ) customers can specify group milestones. To remove all milestones from the release, specify `[]` . |
2020-12-17 16:09:57 -05:00
| `released_at` | datetime | no | The date when the release is/was ready. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
2019-01-04 09:28:40 -05:00
Example request:
2020-01-30 10:09:15 -05:00
```shell
2021-06-02 11:09:59 -04:00
curl --header 'Content-Type: application/json' --request PUT --data '{"name": "new name", "milestones": ["v1.2"]}' \
--header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases/v0.1"
2019-01-04 09:28:40 -05:00
```
Example response:
```json
{
"tag_name":"v0.1",
"description":"## CHANGELOG\r\n\r\n- Remove limit of 100 when searching repository code. !8671\r\n- Show error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\r\n- Fix a bug where internal email pattern wasn't respected. !22516",
"name":"new name",
"created_at":"2019-01-03T01:55:18.203Z",
2019-07-16 07:47:46 -04:00
"released_at":"2019-01-03T01:55:18.203Z",
2019-01-04 09:28:40 -05:00
"author":{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
2019-09-01 19:45:31 -04:00
"web_url":"https://gitlab.example.com/root"
2019-01-04 09:28:40 -05:00
},
"commit":{
"id":"f8d3d94cbd347e924aa7b715845e439d00e80ca4",
"short_id":"f8d3d94c",
"title":"Initial commit",
"created_at":"2019-01-03T01:53:28.000Z",
"parent_ids":[
],
"message":"Initial commit",
"author_name":"Administrator",
"author_email":"admin@example.com",
"authored_date":"2019-01-03T01:53:28.000Z",
"committer_name":"Administrator",
"committer_email":"admin@example.com",
"committed_date":"2019-01-03T01:53:28.000Z"
},
2019-09-16 11:06:26 -04:00
"milestones": [
{
"id":53,
"iid":3,
"project_id":24,
2020-11-09 16:08:48 -05:00
"title":"v1.2",
2019-09-16 11:06:26 -04:00
"description":"Voluptate fugiat possimus quis quod aliquam expedita.",
"state":"active",
"created_at":"2019-09-01T13:00:00.256Z",
"updated_at":"2019-09-01T13:00:00.256Z",
2021-09-06 14:11:17 -04:00
"due_date":"2019-09-20",
"start_date":"2019-09-05",
2020-03-11 14:09:23 -04:00
"web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/3",
"issue_stats": {
"opened": 11,
"closed": 78
}
2019-09-16 11:06:26 -04:00
}
],
2019-09-23 14:06:14 -04:00
"commit_path":"/root/awesome-app/commit/588440f66559714280628a4f9799f0c4eb880a4a",
"tag_path":"/root/awesome-app/-/tags/v0.11.1",
2019-11-19 04:06:16 -05:00
"evidence_sha":"760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d",
2019-01-04 09:28:40 -05:00
"assets":{
"count":4,
"sources":[
{
"format":"zip",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.gz",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.bz2",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar"
2019-01-04 09:28:40 -05:00
}
],
"links":[
2019-11-19 04:06:16 -05:00
],
"evidence_file_path":"https://gitlab.example.com/root/awesome-app/-/releases/v0.1/evidence.json"
2021-04-29 08:09:58 -04:00
}
2019-01-04 09:28:40 -05:00
}
```
## Delete a Release
2021-03-01 19:11:26 -05:00
Delete a release. Deleting a release doesn't delete the associated tag. Maintainer level access to the project is required to delete a release.
2019-01-04 09:28:40 -05:00
2020-02-27 22:09:04 -05:00
```plaintext
2019-01-04 09:28:40 -05:00
DELETE /projects/:id/releases/:tag_name
```
2019-09-01 19:45:31 -04:00
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../index.md#namespaced-path-encoding ). |
2020-11-09 13:09:11 -05:00
| `tag_name` | string | yes | The Git tag the release is associated with. |
2019-01-04 09:28:40 -05:00
Example request:
2020-01-30 10:09:15 -05:00
```shell
2021-01-11 01:10:29 -05:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases/v0.1"
2019-01-04 09:28:40 -05:00
```
Example response:
```json
{
"tag_name":"v0.1",
"description":"## CHANGELOG\r\n\r\n- Remove limit of 100 when searching repository code. !8671\r\n- Show error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\r\n- Fix a bug where internal email pattern wasn't respected. !22516",
"name":"new name",
"created_at":"2019-01-03T01:55:18.203Z",
2019-07-16 07:47:46 -04:00
"released_at":"2019-01-03T01:55:18.203Z",
2019-01-04 09:28:40 -05:00
"author":{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon",
2019-09-01 19:45:31 -04:00
"web_url":"https://gitlab.example.com/root"
2019-01-04 09:28:40 -05:00
},
"commit":{
"id":"f8d3d94cbd347e924aa7b715845e439d00e80ca4",
"short_id":"f8d3d94c",
"title":"Initial commit",
"created_at":"2019-01-03T01:53:28.000Z",
"parent_ids":[
],
"message":"Initial commit",
"author_name":"Administrator",
"author_email":"admin@example.com",
"authored_date":"2019-01-03T01:53:28.000Z",
"committer_name":"Administrator",
"committer_email":"admin@example.com",
"committed_date":"2019-01-03T01:53:28.000Z"
},
2019-09-23 14:06:14 -04:00
"commit_path":"/root/awesome-app/commit/588440f66559714280628a4f9799f0c4eb880a4a",
"tag_path":"/root/awesome-app/-/tags/v0.11.1",
2019-11-19 04:06:16 -05:00
"evidence_sha":"760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d",
2019-01-04 09:28:40 -05:00
"assets":{
"count":4,
"sources":[
{
"format":"zip",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.gz",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar.bz2",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2"
2019-01-04 09:28:40 -05:00
},
{
"format":"tar",
2019-09-01 19:45:31 -04:00
"url":"https://gitlab.example.com/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar"
2019-01-04 09:28:40 -05:00
}
],
"links":[
2019-11-19 04:06:16 -05:00
],
"evidence_file_path":"https://gitlab.example.com/root/awesome-app/-/releases/v0.1/evidence.json"
2021-04-29 08:09:58 -04:00
}
2019-01-04 09:28:40 -05:00
}
```
2019-07-16 07:47:46 -04:00
## Upcoming Releases
2020-05-21 02:08:25 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1.
2019-07-16 07:47:46 -04:00
2021-04-27 14:10:02 -04:00
A release with a `released_at` attribute set to a future date is labeled
as an **Upcoming Release** [in the UI ](../../user/project/releases/index.md#upcoming-releases ).
