Merge branch 'selhorn-release-keyword-updates' into 'master'

Pared down and moved release keyword content

See merge request gitlab-org/gitlab!73108

doc/user/project/releases/index.md

@@ -78,17 +78,172 @@ To create a new release through the GitLab UI:
    [release notes](#release-notes-description), or [assets links](#links).
 1. Click **Create release**.
 
-### Create release from GitLab CI
+## Create a release by using a CI/CD job
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7.
 
-You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/index.md#release)
-by using a `release` node in the job definition.
+You can create a release directly as part of the GitLab CI/CD pipeline
+by using [the `release` keyword](../../../ci/yaml/index.md#release) in the job definition.
 
 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.
 
-### Upcoming releases
+### CI/CD example of the `release` keyword
+
+To create a release when you push a Git tag, or when you add a Git tag
+in the UI by going to **Repository > Tags**:
+
+```yaml
+release_job:
+  stage: release
+  image: registry.gitlab.com/gitlab-org/release-cli:latest
+  rules:
+    - if: $CI_COMMIT_TAG                  # Run this job when a tag is created manually
+  script:
+    - echo 'running release_job'
+  release:
+    name: 'Release $CI_COMMIT_TAG'
+    description: 'Created using the release-cli $EXTRA_DESCRIPTION'  # $EXTRA_DESCRIPTION must be defined
+    tag_name: '$CI_COMMIT_TAG'                                       # elsewhere in the pipeline.
+    ref: '$CI_COMMIT_TAG'
+    milestones:
+      - 'm1'
+      - '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,
+using a new Git tag that is defined with variables:
+
+```yaml
+prepare_job:
+  stage: prepare                                              # This stage must run before the release stage
+  rules:
+    - if: $CI_COMMIT_TAG
+      when: never                                             # Do not run this job when a tag is created manually
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH             # Run this job when commits are pushed or merged to the default branch
+  script:
+    - echo "EXTRA_DESCRIPTION=some message" >> variables.env  # Generate the EXTRA_DESCRIPTION and TAG environment variables
+    - echo "TAG=v$(cat VERSION)" >> variables.env             # and append to the variables.env file
+  artifacts:
+    reports:
+      dotenv: variables.env                                   # Use artifacts:reports:dotenv to expose the variables to other jobs
+
+release_job:
+  stage: release
+  image: registry.gitlab.com/gitlab-org/release-cli:latest
+  needs:
+    - job: prepare_job
+      artifacts: true
+  rules:
+    - if: $CI_COMMIT_TAG
+      when: never                                  # Do not run this job when a tag is created manually
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # Run this job when commits are pushed or merged to the default branch
+  script:
+    - echo 'running release_job for $TAG'
+  release:
+    name: 'Release $TAG'
+    description: 'Created using the release-cli $EXTRA_DESCRIPTION'  # $EXTRA_DESCRIPTION and the $TAG
+    tag_name: '$TAG'                                                 # variables must be defined elsewhere
+    ref: '$CI_COMMIT_SHA'                                            # in the pipeline. For example, in the
+    milestones:                                                      # prepare_job
+      - 'm1'
+      - '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
+```
+
+NOTE:
+Environment variables set in `before_script` or `script` are not available for expanding
+in the same job. Read more about
+[potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400).
+
+### Use a custom SSL CA certificate authority
+
+You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority,
+which is used to verify the peer when the `release-cli` creates a release through the API using HTTPS with custom certificates.
+The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the
+[text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1)
+or the `path/to/file` containing the certificate authority.
+For example, to configure this value in the `.gitlab-ci.yml` file, use the following:
+
+```yaml
+release:
+  variables:
+    ADDITIONAL_CA_CERT_BUNDLE: |
+        -----BEGIN CERTIFICATE-----
+        MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
+        ...
+        jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
+        -----END CERTIFICATE-----
+  script:
+    - echo "Create release"
+  release:
+    name: 'My awesome release'
+    tag_name: '$CI_COMMIT_TAG'
+```
+
+The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a
+[custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables),
+either as a `file`, which requires the path to the certificate, or as a variable,
+which requires the text representation of the certificate.
+
+### `release-cli` command line
+
+The entries under the `release` node are transformed into a `bash` command line and sent
+to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli).
+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" --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}
+```
+
+### Create multiple releases in a single pipeline
+
+A pipeline can have multiple `release` jobs, for example:
+
+```yaml
+ios-release:
+  script:
+    - echo 'iOS release job'
+  release:
+    tag_name: v1.0.0-ios
+    description: 'iOS release v1.0.0'
+
+android-release:
+  script:
+    - echo 'Android release job'
+  release:
+    tag_name: v1.0.0-android
+    description: 'Android release v1.0.0'
+```
+
+### Release assets as Generic packages
+
+You can use [Generic packages](../../packages/generic_packages/index.md) to host your release assets.
+For a complete example, see the [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/)
+project.
+
+## Upcoming releases
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1.
 

doc/user/project/releases/release_cli.md

+---
+type: reference, howto
+stage: Release
+group: Release
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Install the `release-cli` for the Shell executor
+
+> - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8.
+> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/jaime/release-cli/-/packages).
+
+When you use a runner with the Shell executor, you can download and install
+the `release-cli` manually for your [supported OS and architecture](https://release-cli-downloads.s3.amazonaws.com/latest/index.html).
+Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is available to use in your CI/CD jobs.
+
+## Install on Unix/Linux
+
+1. Download the binary for your system from S3, in the following example for amd64 systems:
+
+   ```shell
+   curl --location --output /usr/local/bin/release-cli "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-linux-amd64"
+   ```
+
+   Or from the GitLab Package Registry:
+
+   ```shell
+   curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-darwin-amd64"
+   ```
+
+1. Give it permissions to execute:
+
+   ```shell
+   sudo chmod +x /usr/local/bin/release-cli
+   ```
+
+1. Verify `release-cli` is available:
+
+   ```shell
+   $ release-cli -v
+
+   release-cli version 0.6.0
+   ```
+
+## Install on Windows PowerShell
+
+1. Create a folder somewhere in your system, for example `C:\GitLab\Release-CLI\bin`
+
+   ```shell
+   New-Item -Path 'C:\GitLab\Release-CLI\bin' -ItemType Directory
+   ```
+
+1. Download the executable file:
+
+   ```shell
+   PS C:\> Invoke-WebRequest -Uri "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI\bin\release-cli.exe"
+
+       Directory: C:\GitLab\Release-CLI
+   Mode                LastWriteTime         Length Name
+   ----                -------------         ------ ----
+   d-----        3/16/2021   4:17 AM                bin
+   ```
+
+1. Add the directory to your `$env:PATH`:
+
+   ```shell
+   $env:PATH += ";C:\GitLab\Release-CLI\bin"
+   ```
+
+1. Verify `release-cli` is available:
+
+   ```shell
+   PS C:\> release-cli -v
+
+   release-cli version 0.6.0
+   ```