Add Release example of dynamic metadata

doc/user/project/releases/index.md

@@ -57,8 +57,6 @@ switch between ascending or descending order, select **Sort order**.
 
 ## Create a release
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI.
-
 You can create a release:
 
 - [Using a job in your CI/CD pipeline](#creating-a-release-by-using-a-cicd-job).
@@ -68,13 +66,13 @@ You can create a release:
 
 We recommend creating a release as one of the last steps in your CI/CD pipeline.
 
+### Create a release in the Releases page
+
 Prerequisites:
 
 - You must have at least the Developer role for a project. For more information, read
 [Release permissions](#release-permissions).
 
-### Create a release in the Releases page
-
 To create a release in the Releases page:
 
 1. On the top bar, select **Menu > Projects** and find your project.
@@ -124,8 +122,11 @@ You can create a release directly as part of the GitLab CI/CD pipeline by using
 The release is created only if the job processes without error. If the API returns an error during
 release creation, the release job fails.
 
-For examples of how you can create a release of your application in the CI/CD pipeline,
-see [Release CI/CD examples](release_cicd_examples.md).
+Methods for creating a release using a CI/CD job include:
+
+- [Create a release when a Git tag is created](release_cicd_examples.md#create-a-release-when-a-git-tag-is-created).
+- [Create a release when a commit is merged to the default branch](release_cicd_examples.md#create-a-release-when-a-commit-is-merged-to-the-default-branch).
+- [Create release metadata in a custom script](release_cicd_examples.md#create-release-metadata-in-a-custom-script).
 
 ### Use a custom SSL CA certificate authority
 

doc/user/project/releases/release_cicd_examples.md

@@ -12,9 +12,13 @@ CI/CD pipeline.
 
 ## Create a release when a Git tag is created
 
-In this CI/CD example, pushing a Git tag to the repository, or creating a Git tag in the UI triggers
-the release. You can use this method if you prefer to create the Git tag manually, and create a
-release as a result.
+In this CI/CD example, the release is triggered by one of the following events:
+
+- Pushing a Git tag to the repository.
+- Creating a Git tag in the UI.
+
+You can use this method if you prefer to create the Git tag manually, and create a release as a
+result.
 
 NOTE:
 Do not provide Release notes when you create the Git tag in the UI. Providing release notes
@@ -40,8 +44,8 @@ release_job:
 
 ## Create a release when a commit is merged to the default branch
 
-In this CI/CD example, merging a commit to the default branch triggers the pipeline. You can use
-this method if your release workflow does not create a tag manually.
+In this CI/CD example, the release is triggered when you merge a commit to the default branch. You
+can use this method if your release workflow does not create a tag manually.
 
 Key points in the following _extract_ of an example `.gitlab-ci.yml` file:
 
@@ -69,16 +73,75 @@ Environment variables set in `before_script` or `script` are not available for e
 in the same job. Read more about
 [potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400).
 
+## Create release metadata in a custom script
+
+In this CI/CD example the release preparation is split into separate jobs for greater flexibility:
+
+- The `prepare_job` job generates the release metadata. Any image can be used to run the job,
+  including a custom image. The generated metadata is stored in the variable file `variables.env`.
+  This metadata is [passed to the downstream job](../../../ci/variables/index.md#pass-an-environment-variable-to-another-job).
+- The `release_job` uses the content from the variables file to create a release, using the
+  metadata passed to it in the variables file. This job must use the
+  `registry.gitlab.com/gitlab-org/release-cli:latest` image because it contains the release CLI.
+
+```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
+```
+
 ## Skip multiple pipelines when creating a release
 
 Creating a release using a CI/CD job could potentially trigger multiple pipelines if the associated tag does not exist already. To understand how this might happen, consider the following workflows:
 
 - Tag first, release second:
+
   1. A tag is created via UI or pushed.
   1. A tag pipeline is triggered, and runs `release` job.
   1. A release is created.
 
 - Release first, tag second:
+
   1. A pipeline is triggered when commits are pushed or merged to default branch. The pipeline runs `release` job.
   1. A release is created.
   1. A tag is created.