Add CI_MERGE_REQUEST_DESCRIPTION env variable

Merge requests contain their own description which is comparable to a
`git send-mail` cover letter.

If the merge requests contains only a single commit the merge request
description equal commit description per default. If the merge request
contains multiple commits the description is user defined and ideally
contains a summary of the proposed commits.

For CI purposes the merge request description can contain commands
change the CI default behaviour. This is useful to explicitly run
special cases.

The merge request description could contain a control command like the
following:

```
CI-config: USE_SPECIAL_CASE_Z=1
```

The CI script can evaluate those options via the following command:

```
echo "$CI_MERGE_REQUEST_DESCRIPTION" | grep -e "^CI-config:" \
	cut -d ':' -f 2 | tr ' ' '\n' > extra_env
```

This method allow to run corner cases withouth modifying nor bloating
the git log.
Signed-off-by: Paul Spooren <mail@aparcar.org>

app/models/merge_request.rb

@@ -1324,6 +1324,7 @@ class MergeRequest < ApplicationRecord
       variables.append(key: 'CI_MERGE_REQUEST_PROJECT_URL', value: project.web_url)
       variables.append(key: 'CI_MERGE_REQUEST_TARGET_BRANCH_NAME', value: target_branch.to_s)
       variables.append(key: 'CI_MERGE_REQUEST_TITLE', value: title)
+      variables.append(key: 'CI_MERGE_REQUEST_DESCRIPTION', value: description) if Gitlab::Ci::Features.expose_mr_description_predefined_variable?
       variables.append(key: 'CI_MERGE_REQUEST_ASSIGNEES', value: assignee_username_list) if assignees.present?
       variables.append(key: 'CI_MERGE_REQUEST_MILESTONE', value: milestone.title) if milestone
       variables.append(key: 'CI_MERGE_REQUEST_LABELS', value: label_names.join(',')) if labels.present?

changelogs/unreleased/CI_MERGE_REQUEST_DESCRIPTION.yml

+---
+title: Add CI_MERGE_REQUEST_DESCRIPTION env variable
+merge_request: 40771
+author: Paul Spooren @aparcar
+type: added

config/feature_flags/development/expose_mr_description_predefined_variable.yml

+---
+name: expose_mr_description_predefined_variable
+introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40771
+rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/243556
+group: group::continuous integration
+type: development
+default_enabled: true

doc/ci/variables/predefined_variables.md

@@ -88,7 +88,8 @@ Kubernetes-specific environment variables are detailed in the
 | `CI_MERGE_REQUEST_SOURCE_PROJECT_URL`         | 11.6   | all    | The URL of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                    |
 | `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`         | 11.6   | all    | The target branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                           |
 | `CI_MERGE_REQUEST_TARGET_BRANCH_SHA`          | 11.9   | all    | The HEAD SHA of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)**   |
-| `CI_MERGE_REQUEST_TITLE`                      | 11.9   | all    | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or  [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                                        |
+| `CI_MERGE_REQUEST_TITLE`                      | 11.9   | all    | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                                        |
+| `CI_MERGE_REQUEST_DESCRIPTION`                | 13.3   | all    | The description of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                                        |
 | `CI_MERGE_REQUEST_EVENT_TYPE`                 | 12.3   | all    | The event type of the merge request, if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Can be `detached`, `merged_result` or `merge_train`. |
 | `CI_NODE_INDEX`                               | 11.5   | all    | Index of the job in the job set. If the job is not parallelized, this variable is not set.                                                                                                                                                                                                                                                                 |
 | `CI_NODE_TOTAL`                               | 11.5   | all    | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`.                                                                                                                                                                                                                                    |

lib/gitlab/ci/features.rb

@@ -83,6 +83,10 @@ module Gitlab
       def self.coverage_report_view?(project)
         ::Feature.enabled?(:coverage_report_view, project)
       end
+
+      def self.expose_mr_description_predefined_variable?
+        ::Feature.enabled?(:ci_expose_mr_description_predefined_variable, default_enabled: true)
+      end
     end
   end
 end

spec/models/ci/pipeline_spec.rb

@@ -759,6 +759,7 @@ RSpec.describe Ci::Pipeline, :mailer, factory_default: :keep do
             'CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' => merge_request.source_branch.to_s,
             'CI_MERGE_REQUEST_SOURCE_BRANCH_SHA' => pipeline.source_sha.to_s,
             'CI_MERGE_REQUEST_TITLE' => merge_request.title,
+            'CI_MERGE_REQUEST_DESCRIPTION' => merge_request.description,
             'CI_MERGE_REQUEST_ASSIGNEES' => merge_request.assignee_username_list,
             'CI_MERGE_REQUEST_MILESTONE' => milestone.title,
             'CI_MERGE_REQUEST_LABELS' => labels.map(&:title).sort.join(','),