diff options
| -rw-r--r-- | doc/api/README.md | 3 | ||||
| -rw-r--r-- | doc/api/releases/index.md (renamed from doc/api/releases.md) | 7 | ||||
| -rw-r--r-- | doc/api/releases/links.md | 177 | ||||
| -rw-r--r-- | doc/user/project/releases/index.md | 5 |
4 files changed, 188 insertions, 4 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 3ed1a3799c8..6c5bb1c0940 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -69,6 +69,9 @@ The following API resources are available: - [Sidekiq metrics](sidekiq_metrics.md) - [System hooks](system_hooks.md) - [Tags](tags.md) +- [Releases](releases/index.md) +- Release Assets + - [Links](releases/links.md) - [Todos](todos.md) - [Users](users.md) - [Validate CI configuration](lint.md) (linting) diff --git a/doc/api/releases.md b/doc/api/releases/index.md index 4613fe3482a..943109a3ea9 100644 --- a/doc/api/releases.md +++ b/doc/api/releases/index.md @@ -1,7 +1,8 @@ # Releases API > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. -> - Using this API you can manipulate GitLab's [Release](../user/project/releases/index.md) entries. +> - Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) entries. +> - For manipulating links as a release asset, see [Release Links API](links.md) ## List Releases @@ -241,7 +242,7 @@ POST /projects/:id/releases | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `name` | string | yes | The release name. | | `tag_name` | string | yes | The tag where the release will be created from. | -| `description` | string | no | The description of the release. You can use [markdown](../user/markdown.md). | +| `description` | string | yes | The description of the release. You can use [markdown](../user/markdown.md). | | `ref` | string | no | If `tag_name` doesn't exist, the release will be created from `ref`. It can be a commit SHA, another tag name, or a branch name. | | `assets:links`| array of hash | no | An array of assets links. | | `assets:links:name`| string | no (if `assets:links` specified, it's required) | The name of the link. | @@ -331,8 +332,8 @@ PUT /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag where the release will be created from. | | `name` | string | no | The release name. | -| `tag_name` | string | no | The tag where the release will be created from. | | `description` | string | no | The description of the release. You can use [markdown](../user/markdown.md). | Example request: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md new file mode 100644 index 00000000000..ae99f3bd8b6 --- /dev/null +++ b/doc/api/releases/links.md @@ -0,0 +1,177 @@ +# Release links API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. + +Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) links. For manipulating other Release assets, see [Release API](index.md). + +## Get links + +Get assets as links from a Release. + +``` +GET /projects/:id/releases/:tag_name/assets/links +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links" +``` + +Example response: + +```json +[ + { + "id":2, + "name":"awesome-v0.2.msi", + "url":"http://192.168.10.15:3000/msi", + "external":true + }, + { + "id":1, + "name":"awesome-v0.2.dmg", + "url":"http://192.168.10.15:3000", + "external":true + } +] +``` + +## Get a link + +Get an asset as a link from a Release. + +``` +GET /projects/:id/releases/:tag_name/assets/links/:link_id +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `link_id` | integer | yes | The id of the link. | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1" +``` + +Example response: + +```json +{ + "id":1, + "name":"awesome-v0.2.dmg", + "url":"http://192.168.10.15:3000", + "external":true +} +``` + +## Create a link + +Create an asset as a link from a Release. + +``` +POST /projects/:id/releases/:tag_name/assets/links +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `name` | string | yes | The name of the link. | +| `url` | string | yes | The URL of the link. | + +Example request: + +```sh +curl --request POST \ + --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" \ + --data name="awesome-v0.2.dmg" \ + --data url="http://192.168.10.15:3000" \ + "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links" +``` + +Example response: + +```json +{ + "id":1, + "name":"awesome-v0.2.dmg", + "url":"http://192.168.10.15:3000", + "external":true +} +``` + +## Update a link + +Update an asset as a link from a Release. + +``` +PUT /projects/:id/releases/:tag_name/assets/links/:link_id +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `link_id` | integer | yes | The id of the link. | +| `name` | string | no | The name of the link. | +| `url` | string | no | The URL of the link. | + +NOTE: **NOTE** +You have to specify at least one of `name` or `url` + +Example request: + +```sh +curl --request PUT --data name="new name" --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1" +``` + +Example response: + +```json +{ + "id":1, + "name":"new name", + "url":"http://192.168.10.15:3000", + "external":true +} +``` + +## Delete a link + +Delete an asset as a link from a Release. + +``` +DELETE /projects/:id/releases/:tag_name/assets/links/:link_id +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `link_id` | integer | yes | The id of the link. | + +Example request: + +```sh +curl --request DELETE --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1" +``` + +Example response: + +```json +{ + "id":1, + "name":"new name", + "url":"http://192.168.10.15:3000", + "external":true +} +``` diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 890d6fbc6c7..00a4f6c6a6b 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -12,7 +12,7 @@ GitLab's **Releases** are a way to track deliverables in your project. Consider a snapshot in time of the source, build output, and other metadata or artifacts associated with a released version of your code. -At the moment, you can create Release entries via the [Releases API](../../../api/releases.md); +At the moment, you can create Release entries via the [Releases API](../../../api/releases/index.md); we recommend doing this as one of the last steps in your CI/CD release pipeline. ## Getting started with Releases @@ -51,6 +51,9 @@ A link is any URL which can point to whatever you like; documentation, built binaries, or other related materials. These can be both internal or external links from your GitLab instance. +NOTE: **NOTE** +You can manipulate links of each release entry with [Release Links API](../../../api/releases/links.md) + ## Releases list Navigate to **Project > Releases** in order to see the list of releases for a given |