Merge branch '271454-add-links-to-release-ci-yaml-docs' into 'master'

Add assets:links section to CI reference

See merge request gitlab-org/gitlab!60988

doc/ci/yaml/README.md

@@ -4466,6 +4466,7 @@ These keywords are supported:
 - [`ref`](#releaseref) (optional)
 - [`milestones`](#releasemilestones) (optional)
 - [`released_at`](#releasereleased_at) (optional)
+- [`assets:links`](#releaseassetslinks) (optional)
 
 The release is created only if the job processes without error. If the Rails API
 returns an error during release creation, the `release` job fails.
@@ -4674,6 +4675,26 @@ defined. Should be enclosed in quotes and expressed in ISO 8601 format.
 released_at: '2021-03-15T08:00:00Z'
 ```
 
+#### `release:assets:links`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271454) in GitLab 13.12.
+
+Include [asset links](../../user/project/releases/index.md#release-assets) in the release.
+
+NOTE:
+Requires `release-cli` version v0.4.0 or higher.
+
+```yaml
+assets:
+  links:
+    - name: 'asset1'
+      url: 'https://example.com/assets/1'
+    - name: 'asset2'
+      url: 'https://example.com/assets/2'
+      filepath: '/pretty/url/1' # optional
+      link_type: 'other' # optional
+```
+
 #### Complete example for `release`
 
 If you combine the previous examples for `release`, you get two options, depending on how you generate the
@@ -4700,6 +4721,14 @@ tags. You can't use these options together, so choose one:
         - 'm2'
         - 'm3'
       released_at: '2020-07-15T08:00:00Z'  # Optional, is auto generated if not defined, or can use a variable.
+      assets: # Optional, multiple asset links
+        links:
+          - name: 'asset1'
+            url: 'https://example.com/assets/1'
+          - name: 'asset2'
+            url: 'https://example.com/assets/2'
+            filepath: '/pretty/url/1' # optional
+            link_type: 'other' # optional
   ```
 
 - To create a release automatically when commits are pushed or merged to the default branch,
@@ -4746,6 +4775,14 @@ tags. You can't use these options together, so choose one:
         - 'm2'
         - 'm3'
       released_at: '2020-07-15T08:00:00Z'  # Optional, is auto generated if not defined, or can use a variable.
+      assets:
+        links:
+          - name: 'asset1'
+            url: 'https://example.com/assets/1'
+          - name: 'asset2'
+            url: 'https://example.com/assets/2'
+            filepath: '/pretty/url/1' # optional
+            link_type: 'other' # optional
   ```
 
 #### Release assets as Generic packages
@@ -4763,7 +4800,7 @@ You can also call the `release-cli` directly from a `script` entry.
 For example, if you use the YAML described previously:
 
 ```shell
-release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3"
+release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}
 ```
 
 ### `secrets`

doc/user/project/releases/index.md

@@ -271,10 +271,15 @@ Release note descriptions are unrelated. Description supports [Markdown](../../m
 
 ### Release assets
 
-You can add the following types of assets to each release:
+A release contains the following types of assets:
 
 - [Source code](#source-code)
-- [Links](#links)
+- [Permanent links to release assets](#permanent-links-to-release-assets)
+
+#### Source code
+
+GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar`
+archived source code from the given Git tag. These are read-only assets.
 
 #### Permanent links to release assets
 
@@ -285,9 +290,21 @@ GitLab always redirects this URL to the actual asset
 location, so even if the assets move to a different location, you can continue
 to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link).
 
-Each asset has a name, a URL of the *actual* asset location, and optionally, a
-`filepath` parameter, which, if you specify it, creates a URL pointing
-to the asset for the Release. The format of the URL is:
+Each asset has a `name`, a `url` of the *actual* asset location, and optionally,
+`filepath` and `link_type` parameters.
+
+A `filepath` creates a URL pointing to the asset for the Release.
+
+The `link_type` parameter accepts one of the following four values:
+
+- `runbook`
+- `package`
+- `image`
+- `other` (default)
+
+This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project.
+
+The format of the URL is:
 
 ```plaintext
 https://host/namespace/project/releases/:release/downloads/:filepath
@@ -300,7 +317,8 @@ namespace and `gitlab-runner` project on `gitlab.com`, for example:
 {
   "name": "linux amd64",
   "filepath": "/binaries/gitlab-runner-linux-amd64",
-  "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64"
+  "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64",
+  "link_type": "other"
 }
 ```
 
@@ -312,11 +330,6 @@ https://gitlab.com/gitlab-org/gitlab-runner/releases/v11.9.0-rc2/downloads/binar
 
 The physical location of the asset can change at any time and the direct link remains unchanged.
 
-### Source code
-
-GitLab automatically generates `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