diff options
| -rw-r--r-- | changelogs/unreleased/docs-releases-api.yml | 5 | ||||
| -rw-r--r-- | doc/api/releases.md | 481 | ||||
| -rw-r--r-- | doc/user/project/img/releases.png | bin | 43612 -> 126093 bytes | |||
| -rw-r--r-- | doc/user/project/releases.md | 57 | ||||
| -rw-r--r-- | doc/workflow/releases.md | 12 |
5 files changed, 545 insertions, 10 deletions
diff --git a/changelogs/unreleased/docs-releases-api.yml b/changelogs/unreleased/docs-releases-api.yml new file mode 100644 index 00000000000..fba70c0006d --- /dev/null +++ b/changelogs/unreleased/docs-releases-api.yml @@ -0,0 +1,5 @@ +--- +title: Adds API documentation for releases +merge_request: 23901 +author: +type: added diff --git a/doc/api/releases.md b/doc/api/releases.md new file mode 100644 index 00000000000..bfd0cc1c4ea --- /dev/null +++ b/doc/api/releases.md @@ -0,0 +1,481 @@ +# 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.md) entries. + +## List Releases + +Paginated list of Releases, sorted by `created_at`. + +``` +GET /projects/:id/releases +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases" +``` + +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", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eEscape label and milestone titles to prevent XSS in GFM autocomplete. !2740\u003c/li\u003e\n\u003cli\u003ePrevent private snippets from being embeddable.\u003c/li\u003e\n\u003cli\u003eAdd subresources removal to member destroy service.\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:56:19.539Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "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" + }, + "assets":{ + "count":6, + "sources":[ + { + "format":"zip", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar" + } + ], + "links":[ + { + "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 + } + ] + } + }, + { + "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", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:55:18.203Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "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", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar" + } + ], + "links":[ + + ] + } + } +] +``` + +## Get a Release by a tag name + +Get a Release for the given tag. + +``` +GET /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. | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1" +``` + +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", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:55:18.203Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "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", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar" + } + ], + "links":[ + + ] + } +} +``` + +## Create a release + +Create a Release. You need push access to the repository to create a Release. + +``` +POST /projects/:id/releases +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `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). | +| `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. | +| `assets:links:url`| string | no (if `assets:links` specified, it's required) | The url of the link. | + +Example request: + +```sh +curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" \ + --data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "assets": { "links": [{ "name": "hoge", "url": "https://google.com" }] } }' \ + --request POST http://localhost:3000/api/v4/projects/24/releases +``` + +Example response: + +```json +{ + "tag_name":"v0.3", + "description":"Super nice release", + "name":"New release", + "description_html":"\u003cp dir=\"auto\"\u003eSuper nice release\u003c/p\u003e", + "created_at":"2019-01-03T02:22:45.118Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "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" + }, + "assets":{ + "count":5, + "sources":[ + { + "format":"zip", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar" + } + ], + "links":[ + { + "id":3, + "name":"hoge", + "url":"https://google.com", + "external":true + } + ] + } +} +``` + +## Update a release + +Update a Release. + +``` +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). | +| `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: + +```sh +curl --request PUT --data name="new name" --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1" +``` + +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", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:55:18.203Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "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", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar" + } + ], + "links":[ + + ] + } +} +``` + +## Delete a Release + +Delete a Release. Deleting a Release will not delete the associated tag. + +``` +DELETE /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. | + +Example request: + +```sh +curl --request DELETE --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1" +``` + +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", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:55:18.203Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "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", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar" + } + ], + "links":[ + + ] + } +} +``` diff --git a/doc/user/project/img/releases.png b/doc/user/project/img/releases.png Binary files differindex aec1db89a75..f8b1b7305ad 100644 --- a/doc/user/project/img/releases.png +++ b/doc/user/project/img/releases.png diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md index 8dad4240c91..3f3525829b8 100644 --- a/doc/user/project/releases.md +++ b/doc/user/project/releases.md @@ -2,11 +2,58 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. -Releases mark specific points in a project's development history, communicate -information about the type of change, and deliver on prepared, often compiled, -versions of the software to be reused elsewhere. Currently, releases can only be -created through the API. +It's typical to create a [Git tag](../../university/training/topics/tags.md) at +the moment of release to introduce a checkpoint in your source code +history, but in most cases your users will need compiled objects or other +assets output by your CI system to use them, not just the raw source +code. -Navigate to **Project > Releases** in order to see the list of releases of a project. +GitLab's **Releases** are a way to track deliverables in your project. Consider them +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); +we recommend doing this as one of the last steps in your CI/CD release pipeline. + +## Getting started with Releases + +Start by giving a [description](#release-description) to the Release and +including its [assets](#release-assets), as follows. + +### Release description + +Every Release has a description. You can add any text you like, but we recommend +including a changelog to describe the content of your release. This will allow +your users to quickly scan the differences between each one you publish. + +NOTE: **Note:** +[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) and +Release descriptions are unrelated. Description supports [markdown](../markdown.md). + +### Release assets + +You can currently add the following types of assets to each Release: + +- [Source code](#source-code): state of the repo at the time of the Release +- [Links](#links): to content such as built binaries or documentation + +GitLab will support more asset types in the future, including objects such +as pre-built packages, compliance/security evidence, or container images. + +#### Source code + +GitLab automatically generate `zip`, `tar.gz`, `tar.bz2` and `tar` +archived source code from the given Git tag. These are read-only assets. + +#### Links + +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. + +## Releases list + +Navigate to **Project > Releases** in order to see the list of releases for a given +project.  diff --git a/doc/workflow/releases.md b/doc/workflow/releases.md index 6176784fc57..02388bb73ea 100644 --- a/doc/workflow/releases.md +++ b/doc/workflow/releases.md @@ -1,14 +1,16 @@ # Releases -You can turn any git tag into a release, by adding a note to it. -Release notes behave like any other markdown form in GitLab so you can write text and drag-n-drop files to it. -Release notes are stored in the database of GitLab. +NOTE: In GitLab 11.7, we introduced the full fledged [releases](../user/project/releases.md) feature. You can still create release notes on this page, but the new method is preferred. + +You can add release notes to any git tag using the notes feature. Release notes +behave like any other markdown form in GitLab so you can write text and +drag-n-drop files to it. Release notes are stored in GitLab's database. There are several ways to add release notes: -* In the interface, when you create a new git tag with GitLab +* In the interface, when you create a new git tag * In the interface, by adding a note to an existing git tag -* with the GitLab API +* Using the GitLab API ## New tag page with release notes text area |
