Merge branch 'poffey21-master-patch-31007' into 'master'

Provide example for pre-filled variable pipeline

See merge request gitlab-org/gitlab!51814

doc/ci/pipelines/index.md

@@ -132,10 +132,6 @@ Pipelines can be manually executed, with predefined or manually-specified [varia
 You might do this if the results of a pipeline (for example, a code build) are required outside the normal
 operation of the pipeline.
 
-[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30101),
-all global variables with descriptions defined in the `.gitlab-ci.yml` file are
-displayed in the variable fields.
-
 To execute a pipeline manually:
 
 1. Navigate to your project's **CI/CD > Pipelines**.
@@ -143,10 +139,33 @@ To execute a pipeline manually:
 1. On the **Run Pipeline** page:
     1. Select the branch to run the pipeline for in the **Create for** field.
     1. Enter any [environment variables](../variables/README.md) required for the pipeline run.
+       You can set specific variables to have their [values prefilled in the form](#prefill-variables-in-manual-pipelines).
     1. Click the **Create pipeline** button.
 
 The pipeline now executes the jobs as configured.
 
+#### Prefill variables in manual pipelines
+
+> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7.
+
+You can use the [`value` and `description`](../yaml/README.md#prefill-variables-in-manual-pipelines)
+keywords to define [variables](../variables/README.md) that are prefilled when running
+a pipeline manually.
+
+In pipelines triggered manually, the **Run pipelines** page displays all variables
+with a `description` and `value` defined in the `.gitlab-ci.yml` file. The values
+can then be modified if needed, which overrides the value for that single pipeline run.
+
+The description is displayed below the variable. It can be used to explain what
+the variable is used for, what the acceptable values are, and so on:
+
+```yaml
+variables:
+  DEPLOY_ENVIRONMENT:
+    value: "staging"  # Deploy to staging by default
+    description: "The deployment target. Change this variable to 'canary' or 'production' if needed."
+```
+
 ### Run a pipeline by using a URL query string
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24146) in GitLab 12.5.

doc/ci/variables/README.md

@@ -70,7 +70,8 @@ When you need a specific custom environment variable, you can
 or directly [in the `.gitlab-ci.yml` file](#create-a-custom-variable-in-gitlab-ciyml).
 
 The variables are used by the runner any time the pipeline runs.
-You can also [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs).
+You can also [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs),
+or have them [prefilled in manual pipelines](../pipelines/index.md#prefill-variables-in-manual-pipelines).
 
 There are two types of variables: **Variable** and **File**. You cannot set types in
 the `.gitlab-ci.yml` file, but you can set them in the UI and API.
@@ -406,6 +407,10 @@ script:
   - 'eval $LS_CMD'  # will execute 'ls -al $TMP_DIR'
 ```
 
+Use the [`value` and `description`](../yaml/README.md#prefill-variables-in-manual-pipelines)
+keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines)
+when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually):
+
 ## Group-level environment variables
 
 > Introduced in GitLab 9.4.

doc/ci/yaml/README.md

@@ -4235,7 +4235,8 @@ There are two types of variables.
 
 - [Custom variables](../variables/README.md#custom-environment-variables):
   You can define their values in the `.gitlab-ci.yml` file, in the GitLab UI,
-  or by using the API.
+  or by using the API. You can also input variables in the GitLab UI when
+  [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually).
 - [Predefined variables](../variables/predefined_variables.md):
   These values are set by the runner itself.
   One example is `CI_COMMIT_REF_NAME`, which is the branch or tag the project is built for.
@@ -4275,6 +4276,20 @@ All YAML-defined variables are also set to any linked
 
 You can use [YAML anchors for variables](#yaml-anchors-for-variables).
 
+### Prefill variables in manual pipelines
+
+> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7.
+
+You can use the `value` and `description` keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines)
+when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually):
+
+```yaml
+variables:
+  DEPLOY_ENVIRONMENT:
+    value: "staging"  # Deploy to staging by default
+    description: "The deployment target. Change this variable to 'canary' or 'production' if needed."
+```
+
 ### Configure runner behavior with variables
 
 You can use [CI/CD variables](../variables/README.md) to configure runner Git behavior: