diff options
Diffstat (limited to 'doc/api/releases/index.md')
| -rw-r--r-- | doc/api/releases/index.md | 65 |
1 files changed, 59 insertions, 6 deletions
diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index e3b1d9230f6..66d5775f499 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -28,7 +28,7 @@ For authentication, the Releases API accepts either: > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72448) to allow for `JOB-TOKEN` in GitLab 14.5. -Paginated list of Releases, sorted by `released_at`. +Returns a paginated list of releases, sorted by `released_at`. ```plaintext GET /projects/:id/releases @@ -235,7 +235,7 @@ Example response: > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72448) to allow for `JOB-TOKEN` in GitLab 14.5. -Get a Release for the given tag. +Gets a release for the given tag. ```plaintext GET /projects/:id/releases/:tag_name @@ -364,9 +364,62 @@ Example response: } ``` +## Download a release asset + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358188) in GitLab 15.4. + +Download a release asset file by making a request with the following format: + +```plaintext +GET /projects/:id/releases/:tag_name/downloads/:filepath +``` + +| Attribute | Type | Required | Description | +|----------------------------| -------------- | -------- | ----------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The Git tag the release is associated with. | +| `filepath` | string | yes | Path to the release asset file as specified when [creating](links.md#create-a-release-link) or [updating](links.md#update-a-release-link) its link. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/downloads/bin/asset.exe" +``` + +### Get the latest release + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358188) in GitLab 15.4. + +Latest release information is accessible through a permanent API URL. + +The format of the URL is: + +```plaintext +GET /projects/:id/releases/permalink/latest +``` + +To call any other GET API that requires a release tag, append a suffix to the `permalink/latest` API path. + +For example, to get latest [release evidence](#collect-release-evidence) you can use: + +```plaintext +GET /projects/:id/releases/permalink/latest/evidence +``` + +Another example is [downloading an asset](#download-a-release-asset) of the latest release, for which you can use: + +```plaintext +GET /projects/:id/releases/permalink/latest/downloads/bin/asset.exe +``` + +#### Sorting preferences + +By default, GitLab fetches the release using `released_at` time. The use of the query parameter +`?order_by=released_at` is optional, and support for `?order_by=semver` is tracked [in issue 352945](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). + ## Create a release -Create a release. Developer level access to the project is required to create a release. +Creates a release. Developer level access to the project is required to create a release. ```plaintext POST /projects/:id/releases @@ -516,7 +569,7 @@ adding milestones for ancestor groups raises an error. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in GitLab 12.10. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72448) to allow for `JOB-TOKEN` in GitLab 14.5. -Create Evidence for an existing Release. +Creates an evidence for an existing release. ```plaintext POST /projects/:id/releases/:tag_name/evidence @@ -543,7 +596,7 @@ Example response: > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72448) to allow for `JOB-TOKEN` in GitLab 14.5. -Update a release. Developer level access to the project is required to update a release. +Updates a release. Developer level access to the project is required to update a release. ```plaintext PUT /projects/:id/releases/:tag_name @@ -652,7 +705,7 @@ Example response: > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72448) to allow for `JOB-TOKEN` in GitLab 14.5. -Delete a release. Deleting a release doesn't delete the associated tag. Maintainer level access to the project is required to delete a release. +Deletes a release. Deleting a release doesn't delete the associated tag. Maintainer level access to the project is required to delete a release. ```plaintext DELETE /projects/:id/releases/:tag_name |