Documentation for On-Demand Release Evidence

Part of https://gitlab.com/gitlab-org/gitlab/issues/199065

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26760

doc/api/releases/index.md

@@ -308,7 +308,12 @@ Example response:
          }
       ],
       "links":[
-
+         {
+            "id":3,
+            "name":"hoge",
+            "url":"https://gitlab.example.com/root/awesome-app/-/tags/v0.11.1/binaries/linux-amd64",
+            "external":true
+         }
       ],
       "evidence_url":"https://gitlab.example.com/root/awesome-app/-/releases/v0.1/evidence.json"
    },
@@ -334,13 +339,14 @@ POST /projects/:id/releases
 | `assets:links`     | array of hash   | no                          | An array of assets links.                                                                                                        |
 | `assets:links:name`| string          | required by: `assets:links` | The name of the link.                                                                                                            |
 | `assets:links:url` | string          | required by: `assets:links` | The url of the link.                                                                                                             |
+| `assets:links:filepath` | string     | no | Optional path for a [Direct Asset link](../../user/project/releases.md).
 | `released_at`      | datetime        | no                          | The date when the release will be/was ready. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
 
 Example request:
 
 ```shell
 curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" \
-     --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" }] } }' \
+     --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" }] } }' \
      --request POST https://gitlab.example.com/api/v4/projects/24/releases
 ```
 
@@ -441,7 +447,7 @@ Example response:
          {
             "id":3,
             "name":"hoge",
-            "url":"https://google.com",
+            "url":"https://gitlab.example.com/root/awesome-app/-/tags/v0.11.1/binaries/linux-amd64",
             "external":true
          }
       ],

doc/user/project/releases/index.md

@@ -67,7 +67,43 @@ links from your GitLab instance.
 NOTE: **NOTE**
 You can manipulate links of each release entry with [Release Links API](../../../api/releases/links.md)
 
-#### Releases associated with milestones
+#### Permanent links to Release assets
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27300) in GitLab 12.9.
+
+The assets associated with a Release are accessible through a permanent URL.
+GitLab will always redirect 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, will create a URL pointing
+to the asset for the Release. The format of the URL is:
+
+```html
+https://host/namespace/project/releases/:release/downloads/:filepath
+```
+
+If you have an asset for the `v11.9.0-rc2` release in the `gitlab-org`
+namespace and `gitlab-runner` project on `gitlab.com`, for example:
+
+```json
+{
+  "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"
+}
+```
+
+This asset has a direct link of:
+
+```html
+https://gitlab.com/gitlab-org/gitlab-runner/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64
+```
+
+The physical location of the asset can change at any time and the direct link will remain unchanged.
+
+### Releases associated with milestones
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29020) in GitLab 12.5.