Add latest changes from gitlab-org/gitlab@14-2-stable-eev14.2.0-rc42

4 files changed, 415 insertions, 382 deletions

diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 5ab8653dc35..0e6c2f63f9e 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1,5 +1,6 @@
 ---
 redirect_to: 'index.md'
+remove_date: '2021-09-28'
 ---
 
 This document was moved to [another location](index.md).
diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md
index 2723cb19c1f..6cd900123e0 100644
--- a/doc/ci/yaml/gitlab_ci_yaml.md
+++ b/doc/ci/yaml/gitlab_ci_yaml.md
@@ -4,11 +4,8 @@ group: Pipeline Execution
 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/#designated-technical-writers
 type: reference
 ---
-<!-- markdownlint-disable MD044 -->
-<!-- vale gitlab.Spelling = NO -->
-# The .gitlab-ci.yml file **(FREE)**
-<!-- vale gitlab.Spelling = YES -->
-<!-- markdownlint-enable MD044 -->
+
+# The `.gitlab-ci.yml` file **(FREE)**
 
 To use GitLab CI/CD, you need:
 
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index c2b8ef50e6a..63f626e524e 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -126,6 +126,15 @@ Use `stages` to define stages that contain groups of jobs. `stages` is defined g
 for the pipeline. Use [`stage`](#stage) in a job to define which stage the job is
 part of.
 
+If `stages` is not defined in the `.gitlab-ci.yml` file, then the default
+pipeline stages are:
+
+- [`.pre`](#stage-pre)
+- `build`
+- `test`
+- `deploy`
+- [`.post`](#stage-post)
+
 The order of the `stages` items defines the execution order for jobs:
 
 - Jobs in the same stage run in parallel.
@@ -148,9 +157,6 @@ stages:
 If any job fails, the pipeline is marked as `failed` and jobs in later stages do not
 start. Jobs in the current stage are not stopped and continue to run.
 
-If no `stages` are defined in the `.gitlab-ci.yml` file, then `build`, `test` and `deploy`
-are the default pipeline stages.
-
 If a job does not specify a [`stage`](#stage), the job is assigned the `test` stage.
 
 If a stage is defined, but no jobs use it, the stage is not visible in the pipeline. This is
@@ -415,13 +421,20 @@ NOTE:
 Use merging to customize and override included CI/CD configurations with local
 configurations. Local configurations in the `.gitlab-ci.yml` file override included configurations.
 
-#### Variables with `include` **(FREE SELF)**
+#### Variables with `include`
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/284883) in GitLab 13.8.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294294) in GitLab 13.9.
+> - [Support for project, group, and instance variables added](https://gitlab.com/gitlab-org/gitlab/-/issues/219065) in GitLab 14.2.
+
+In `include` sections in your `.gitlab-ci.yml` file, you can use:
 
-You can [use some predefined variables in `include` sections](../variables/where_variables_can_be_used.md#gitlab-ciyml-file)
-in your `.gitlab-ci.yml` file:
+- `$CI_COMMIT_REF_NAME` [predefined variable](../variables/predefined_variables.md) in GitLab 14.2
+  and later.
+- [Project variables](../variables/index.md#add-a-cicd-variable-to-a-project)
+- [Group variables](../variables/index.md#add-a-cicd-variable-to-a-group)
+- [Instance variables](../variables/index.md#add-a-cicd-variable-to-an-instance)
+- Project [predefined variables](../variables/predefined_variables.md).   
 
 ```yaml
 include:
@@ -432,6 +445,32 @@ include:
 For an example of how you can include these predefined variables, and the variables' impact on CI/CD jobs,
 see this [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos).
 
+There is a [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337633)
+that proposes expanding this feature to support more variables.
+
+#### `rules` with `include`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276515) in GitLab 14.2.
+
+NOTE:
+On self-managed GitLab, by default this feature is not available. To make it available,
+ask an administrator to [enable the `ci_include_rules` flag](../../administration/feature_flags.md).
+On GitLab.com, this feature is not available. The feature is not ready for production use.
+
+You can use [`rules`](#rules) with `include` to conditionally include other configuration files.
+You can only use `rules:if` in `include` with [certain variables](#variables-with-include).
+
+```yaml
+include:
+  - local: builds.yml
+    rules:
+      - if: '$INCLUDE_BUILDS == "true"'
+
+test:
+  stage: test
+  script: exit 0
+```
+
 #### `include:local`
 
 Use `include:local` to include a file that is in the same repository as the `.gitlab-ci.yml` file.
@@ -463,15 +502,7 @@ Use local includes instead of symbolic links.
 ##### `include:local` with wildcard file paths
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25921) in GitLab 13.11.
-> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/327315) in GitLab 13.12.
-> - Enabled on GitLab.com.
-> - Recommended for production use.
-> - For GitLab self-managed instances, GitLab administrators can opt to disable it. **(CORE ONLY)**
-
-There can be
-[risks when disabling released features](../../user/feature_flags.md#risks-when-disabling-released-features).
-Refer to this feature's version history for more details.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327315) in GitLab 14.2.
 
 You can use wildcard paths (`*` and `**`) with `include:local`.
 
@@ -495,23 +526,6 @@ When the pipeline runs, GitLab:
   include: 'configs/**/*.yml'
   ```
 
-The wildcard file paths feature is under development but ready for production use.
-It is deployed behind a feature flag that is **enabled by default**.
-[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
-can opt to disable it.
-
-To enable it:
-
-```ruby
-Feature.enable(:ci_wildcard_file_paths)
-```
-
-To disable it:
-
-```ruby
-Feature.disable(:ci_wildcard_file_paths)
-```
-
 #### `include:file`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7.
@@ -680,160 +694,148 @@ For more information, see [Available settings for `services`](../services/index.
 
 ### `script`
 
-Use `script` to specify a shell script for the runner to execute.
+Use `script` to specify commands for the runner to execute.
 
 All jobs except [trigger jobs](#trigger) require a `script` keyword.
 
-For example:
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-```yaml
-job:
-  script: "bundle exec rspec"
-```
+**Possible inputs**: An array including:
 
-You can use [YAML anchors with `script`](#yaml-anchors-for-scripts).
+- Single line commands.
+- Long commands [split over multiple lines](script.md#split-long-commands).
+- [YAML anchors](#yaml-anchors-for-scripts).
 
-The `script` keyword can also contain several commands in an array:
+**Example of `script`:**
 
 ```yaml
-job:
+job1:
+  script: "bundle exec rspec"
+
+job2:
   script:
     - uname -a
     - bundle exec rspec
 ```
 
-Sometimes, `script` commands must be wrapped in single or double quotes.
-For example, commands that contain a colon (`:`) must be wrapped in single quotes (`'`).
-The YAML parser needs to interpret the text as a string rather than
-a "key: value" pair.
+**Additional details**:
 
-For example, this script uses a colon:
+You might need to use single quotes (`'`) or double quotes (`"`) when using
+[special characters in `script`](script.md#use-special-characters-with-script).
 
-```yaml
-job:
-  script:
-    - curl --request POST --header 'Content-Type: application/json' "https://gitlab/api/v4/projects"
-```
+**Related topics**:
+
+- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes).
+- [Use color codes with `script`](script.md#add-color-codes-to-script-output)
+  to make job logs easier to review.
+- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections)
+  to simplify job log output.
 
-To be considered valid YAML, you must wrap the entire command in single quotes. If
-the command already uses single quotes, you should change them to double quotes (`"`)
-if possible:
+#### `before_script`
 
-```yaml
-job:
-  script:
-    - 'curl --request POST --header "Content-Type: application/json" "https://gitlab/api/v4/projects"'
-```
+Use `before_script` to define an array of commands that should run before each job's
+`script` commands, but after [artifacts](#artifacts) are restored.
 
-You can verify the syntax is valid with the [CI Lint](../lint.md) tool.
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#custom-default-keyword-values).
 
-Be careful when using these characters as well:
+**Possible inputs**: An array including:
 
-- `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
+- Single line commands.
+- Long commands [split over multiple lines](script.md#split-long-commands).
+- [YAML anchors](#yaml-anchors-for-scripts).
 
-If any of the script commands return an exit code other than zero, the job
-fails and further commands are not executed. Store the exit code in a variable to
-avoid this behavior:
+**Example of `before_script`:**
 
 ```yaml
 job:
+  before_script:
+    - echo "Execute this command before any `script:` commands."
   script:
-    - false || exit_code=$?
-    - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;
+    - echo "This command executes after the job's `before_script` commands."
 ```
 
-#### `before_script`
-
-Use `before_script` to define an array of commands that should run before each job,
-but after [artifacts](#artifacts) are restored.
+**Additional details**:
 
 Scripts you specify in `before_script` are concatenated with any scripts you specify
-in the main [`script`](#script). The combine scripts execute together in a single shell.
+in the main [`script`](#script). The combined scripts execute together in a single shell.
 
-You can overwrite a globally-defined `before_script` if you define it in a job:
+**Related topics**:
 
-```yaml
-default:
-  before_script:
-    - echo "Execute this script in all jobs that don't already have a before_script section."
+- [Use `before_script` with `default`](script.md#set-a-default-before_script-or-after_script-for-all-jobs)
+  to define a default array of commands that should run before the `script` commands in all jobs.
+- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes).
+- [Use color codes with `before_script`](script.md#add-color-codes-to-script-output)
+  to make job logs easier to review.
+- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections)
+  to simplify job log output.
 
-job1:
-  script:
-    - echo "This script executes after the global before_script."
+#### `after_script`
 
-job:
-  before_script:
-    - echo "Execute this script instead of the global before_script."
-  script:
-    - echo "This script executes after the job's `before_script`"
-```
+Use `after_script` to define an array of commands that run after each job, including failed jobs.
 
-You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts).
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#custom-default-keyword-values).
 
-#### `after_script`
+**Possible inputs**: An array including:
 
-Use `after_script` to define an array of commands that run after each job,
-including failed jobs.
+- Single line commands.
+- Long commands [split over multiple lines](script.md#split-long-commands).
+- [YAML anchors](#yaml-anchors-for-scripts).
 
-If a job times out or is cancelled, the `after_script` commands do not execute.
-An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15603) exists to support
-executing `after_script` commands for timed-out or cancelled jobs.
+**Example of `after_script`:**
+
+```yaml
+job:
+  script:
+    - echo "An example script section."
+  after_script:
+    - echo "Execute this command after the `script` section completes."
+```
+
+**Additional details**:
 
 Scripts you specify in `after_script` execute in a new shell, separate from any
-`before_script` or `script` scripts. As a result, they:
+`before_script` or `script` commands. As a result, they:
 
 - Have a current working directory set back to the default.
-- Have no access to changes done by scripts defined in `before_script` or `script`, including:
+- Don't have access to changes done by commands defined in the `before_script` or `script`,
+  including:
   - Command aliases and variables exported in `script` scripts.
   - Changes outside of the working tree (depending on the runner executor), like
     software installed by a `before_script` or `script` script.
-- Have a separate timeout, which is hard coded to 5 minutes. See the
-  [related issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716) for details.
+- Have a separate timeout, which is [hard-coded to 5 minutes](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716).
 - Don't affect the job's exit code. If the `script` section succeeds and the
   `after_script` times out or fails, the job exits with code `0` (`Job Succeeded`).
 
-```yaml
-default:
-  after_script:
-    - echo "Execute this script in all jobs that don't already have an after_script section."
-
-job1:
-  script:
-    - echo "This script executes first. When it completes, the global after_script executes."
-
-job:
-  script:
-    - echo "This script executes first. When it completes, the job's `after_script` executes."
-  after_script:
-    - echo "Execute this script instead of the global after_script."
-```
-
-You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts).
-
-#### Script syntax
+If a job times out or is cancelled, the `after_script` commands do not execute.
+[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/15603) to add support for executing `after_script` commands for timed-out or cancelled jobs.
 
-You can use syntax in [`script`](#script) sections to:
+**Related topics**:
 
-- [Split long commands](script.md#split-long-commands) into multiline commands.
-- [Use color codes](script.md#add-color-codes-to-script-output) to make job logs easier to review.
+- [Use `after_script` with `default`](script.md#set-a-default-before_script-or-after_script-for-all-jobs)
+  to define a default array of commands that should run after all jobs.
+- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes).
+- [Use color codes with `after_script`](script.md#add-color-codes-to-script-output)
+  to make job logs easier to review.
 - [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections)
   to simplify job log output.
 
 ### `stage`
 
-Use `stage` to define which stage a job runs in. Jobs in the same
-`stage` can execute in parallel (subject to [certain conditions](#use-your-own-runners)).
+Use `stage` to define which [stage](#stages) a job runs in. Jobs in the same
+`stage` can execute in parallel (see **Additional details**).
 
-Jobs without a `stage` entry use the `test` stage by default. If you do not define
-[`stages`](#stages) in the pipeline, you can use the 5 default stages, which execute in
-this order:
+If `stage` is not defined, the job uses the `test` stage by default.
 
-- [`.pre`](#pre-and-post)
-- `build`
-- `test`
-- `deploy`
-- [`.post`](#pre-and-post)
-For example:
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: An array including any number of stage names. Stage names can be:
+
+- The [default stages](#stages).
+- User-defined stages.
+
+**Example of `stage`**:
 
 ```yaml
 stages:
@@ -841,76 +843,101 @@ stages:
   - test
   - deploy
 
-job 0:
-  stage: .pre
-  script: make something useful before build stage
-
-job 1:
-  stage: build
-  script: make build dependencies
-
-job 2:
+job1:
   stage: build
-  script: make build artifacts
+  script:
+    - echo "This job compiles code."
 
-job 3:
+job2:
   stage: test
-  script: make test
+  script:
+    - echo "This job tests the compiled code. It runs when the build stage completes."
 
-job 4:
-  stage: deploy
-  script: make deploy
+job3:
+  script:
+    - echo "This job also runs in the test stage".
 
-job 5:
-  stage: .post
-  script: make something useful at the end of pipeline
+job4:
+  stage: deploy
+  script:
+    - echo "This job deploys the code. It runs when the test stage completes."
 ```
 
-#### Use your own runners
-
-When you use your own runners, each runner runs only one job at a time by default.
-Jobs can run in parallel if they run on different runners.
+**Additional details**:
 
-If you have only one runner, jobs can run in parallel if the runner's
-[`concurrent` setting](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section)
-is greater than `1`.
+- Jobs can run in parallel if they run on different runners.
+- If you have only one runner, jobs can run in parallel if the runner's
+  [`concurrent` setting](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section)
+  is greater than `1`.
 
-#### `.pre` and `.post`
+#### `stage: .pre`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4.
 
-Use `pre` and `post` for jobs that need to run first or last in a pipeline.
-
-- `.pre` is guaranteed to always be the first stage in a pipeline.
-- `.post` is guaranteed to always be the last stage in a pipeline.
-
-User-defined stages are executed after `.pre` and before `.post`.
+Use the `.pre` stage to make a job run at the start of a pipeline. `.pre` is
+always the first stage in a pipeline. User-defined stages execute after `.pre`.
+You do not need to define `.pre` in [`stages`](#stages).
 
 You must have a job in at least one stage other than `.pre` or `.post`.
 
-You can't change the order of `.pre` and `.post`, even if you define them out of order in the `.gitlab-ci.yml` file.
-For example, the following configurations are equivalent:
+**Keyword type**: You can only use it with a job's `stage` keyword.
 
-```yaml
-stages:
-  - .pre
-  - a
-  - b
-  - .post
-```
+**Example of `stage: .pre`**:
 
 ```yaml
 stages:
-  - a
-  - .pre
-  - b
-  - .post
+  - build
+  - test
+
+job1:
+  stage: build
+  script:
+    - echo "This job runs in the build stage."
+
+first-job:
+  stage: .pre
+  script:
+    - echo "This job runs in the .pre stage, before all other stages."
+
+job2:
+  stage: test
+  script:
+    - echo "This job runs in the test stage."
 ```
 
+#### `stage: .post`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4.
+
+Use the `.post` stage to make a job run at the end of a pipeline. `.post`
+is always the last stage in a pipeline. User-defined stages execute before `.post`.
+You do not need to define `.post` in [`stages`](#stages).
+
+You must have a job in at least one stage other than `.pre` or `.post`.
+
+**Keyword type**: You can only use it with a job's `stage` keyword.
+
+**Example of `stage: .post`**:
+
 ```yaml
 stages:
-  - a
-  - b
+  - build
+  - test
+
+job1:
+  stage: build
+  script:
+    - echo "This job runs in the build stage."
+
+last-job:
+  stage: .post
+  script:
+    - echo "This job runs in the .post stage, after all other stages."
+
+job2:
+  stage: test
+  script:
+    - echo "This job runs in the test stage."
 ```
 
 ### `extends`
@@ -1504,6 +1531,7 @@ in the project.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) in GitLab 12.2.
 > - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) in GitLab 12.8, `needs: []` lets jobs start immediately.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) in GitLab 14.2, you can refer to jobs in the same stage as the job you are configuring.
 
 Use `needs:` to execute jobs out-of-order. Relationships between jobs
 that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md).
@@ -1563,13 +1591,11 @@ production:
 
 #### Requirements and limitations
 
-- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632)
-  you can refer to jobs in the same stage as the job you are configuring. This feature
-  is [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
-- Disabled on GitLab.com.
-- Not recommended for production use.
-- For GitLab self-managed instances, GitLab adminsitrators
-  can choose to [disable it](#enable-or-disable-needs-for-jobs-in-the-same-stage)
+- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you
+  can refer to jobs in the same stage as the job you are configuring. This feature is
+  enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632)
+  this feature is available by default. To hide the feature, ask an administrator to
+  [disable the `ci_same_stage_job_needs` flag](../../administration/feature_flags.md).
 - In GitLab 14.0 and older, you can only refer to jobs in earlier stages.
 - In GitLab 13.9 and older, if `needs:` refers to a job that might not be added to
   a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create.
@@ -1583,26 +1609,10 @@ production:
   name, they overwrite each other and only the last one downloaded is saved.
 - `needs:` is similar to `dependencies:` in that it must use jobs from prior stages,
   meaning it's impossible to create circular dependencies. Depending on jobs in the
-  current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/30632).
+  current stage is not possible either, but [an issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/30632).
 - Stages must be explicitly defined for all jobs
   that have the keyword `needs:` or are referred to by one.
 
-##### Enable or disable `needs` for jobs in the same stage **(FREE SELF)**
-
-`needs` for jobs in the same stage is under development but ready for production use.
-It is deployed behind a feature flag that is **enabled by default**.
-[GitLab administrators with access to the GitLab Rails
-console](../../administration/feature_flags.md)
-can opt to disable it.
-
-To enable it:
-
-`Feature.enable(:ci_same_stage_job_needs)`
-
-To disable it:
-
-`Feature.disable(:ci_same_stage_job_needs)`
-
 ##### Changing the `needs:` job limit **(FREE SELF)**
 
 The maximum number of jobs that can be defined in `needs:` defaults to 50.
@@ -1860,11 +1870,26 @@ osx job:
     - echo "Hello, $USER!"
 ```
 
+In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/35742), you can
+use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection:
+
+```yaml
+variables:
+  KUBERNETES_RUNNER: kubernetes
+
+  job:
+    tags:
+      - docker
+      - $KUBERNETES_RUNNER
+    script:
+      - echo "Hello runner selector feature"
+```
+
 ### `allow_failure`
 
 Use `allow_failure` when you want to let a job fail without impacting the rest of the CI
-suite. The default value is `false`, except for [manual](#whenmanual) jobs that use
-the `when: manual` syntax.
+suite. The default value is `false`, except for [manual](../jobs/job_control.md#create-a-job-that-must-be-run-manually) jobs that use
+the [`when: manual`](#when) syntax.
 
 In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`,
 *including* `when: manual` jobs.
@@ -1928,28 +1953,23 @@ test_job_2:
 
 ### `when`
 
-Use `when` to implement jobs that run in case of failure or despite the
-failure.
+Use `when` to configure the conditions for when jobs run. If not defined in a job,
+the default value is `when: on_success`.
 
-The valid values of `when` are:
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed,
-    or are considered successful because they have `allow_failure: true`.
-1. `on_failure` - Execute job only when at least one job in an earlier stage fails.
-1. `always` - Execute job regardless of the status of jobs in earlier stages.
-1. `manual` - Execute job [manually](#whenmanual).
-1. `delayed` - [Delay the execution of a job](#whendelayed) for a specified duration.
-    Added in GitLab 11.14.
-1. `never`:
-   - With job [`rules`](#rules), don't execute job.
-   - With [`workflow:rules`](#workflow), don't run pipeline.
+**Possible inputs**:
 
-In the following example, the script:
+- `on_success` (default): Run the job only when all jobs in earlier stages succeed
+  or have `allow_failure: true`.
+- `manual`: Run the job only when [triggered manually](../jobs/job_control.md#create-a-job-that-must-be-run-manually).
+- `always`: Run the job regardless of the status of jobs in earlier stages.
+- `on_failure`: Run the job only when at least one job in an earlier stage fails.
+- `delayed`: [Delay the execution of a job](../jobs/job_control.md#run-a-job-after-a-delay)
+  for a specified duration.
+- `never`: Don't run the job.
 
-1. Executes `cleanup_build_job` only when `build_job` fails.
-1. Always executes `cleanup_job` as the last step in pipeline regardless of
-   success or failure.
-1. Executes `deploy_job` when you run it manually in the GitLab UI.
+**Example of `when`**:
 
 ```yaml
 stages:
@@ -1988,116 +2008,26 @@ cleanup_job:
   when: always
 ```
 
-#### `when:manual`
-
-A manual job is a type of job that is not executed automatically and must be explicitly
-started by a user. You might want to use manual jobs for things like deploying to production.
-
-To make a job manual, add `when: manual` to its configuration.
-
-When the pipeline starts, manual jobs display as skipped and do not run automatically.
-They can be started from the pipeline, job, [environment](../environments/index.md#configure-manual-deployments),
-and deployment views.
-
-Manual jobs can be either optional or blocking:
-
-- **Optional**: Manual jobs have [`allow_failure: true](#allow_failure) set by default
-  and are considered optional. The status of an optional manual job does not contribute
-  to the overall pipeline status. A pipeline can succeed even if all its manual jobs fail.
-
-- **Blocking**: To make a blocking manual job, add `allow_failure: false` to its configuration.
-  Blocking manual jobs stop further execution of the pipeline at the stage where the
-  job is defined. To let the pipeline continue running, click **{play}** (play) on
-  the blocking manual job.
-
-  Merge requests in projects with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md)
-  enabled can't be merged with a blocked pipeline. Blocked pipelines show a status
-  of **blocked**.
-
-When you use [`rules:`](#rules), `allow_failure` defaults to `false`, including for manual jobs.
-
-To trigger a manual job, a user must have permission to merge to the assigned branch.
-You can use [protected branches](../../user/project/protected_branches.md) to more strictly
-[protect manual deployments](#protecting-manual-jobs) from being run by unauthorized users.
-
-In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you
-can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and
-earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`.
-
-##### Protecting manual jobs **(PREMIUM)**
-
-Use [protected environments](../environments/protected_environments.md)
-to define a list of users authorized to run a manual job. You can authorize only
-the users associated with a protected environment to trigger manual jobs, which can:
-
-- More precisely limit who can deploy to an environment.
-- Block a pipeline until an approved user "approves" it.
-
-To protect a manual job:
-
-1. Add an `environment` to the job. For example:
-
-   ```yaml
-   deploy_prod:
-     stage: deploy
-     script:
-       - echo "Deploy to production server"
-     environment:
-       name: production
-       url: https://example.com
-     when: manual
-     rules:
-       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-   ```
+In this example, the script:
 
-1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
-   select the environment (`production` in this example) and add the users, roles or groups
-   that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in
-   this list can trigger this manual job, as well as GitLab administrators
-   who are always able to use protected environments.
-
-You can use protected environments with blocking manual jobs to have a list of users
-allowed to approve later pipeline stages. Add `allow_failure: false` to the protected
-manual job and the pipeline's next stages only run after the manual job is triggered
-by authorized users.
-
-#### `when:delayed`
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) in GitLab 11.4.
-
-Use `when: delayed` to execute scripts after a waiting period, or if you want to avoid
-jobs immediately entering the `pending` state.
-
-You can set the period with `start_in` keyword. The value of `start_in` is an elapsed time in seconds, unless a unit is
-provided. `start_in` must be less than or equal to one week. Examples of valid values include:
-
-- `'5'`
-- `5 seconds`
-- `30 minutes`
-- `1 day`
-- `1 week`
-
-When a stage includes a delayed job, the pipeline doesn't progress until the delayed job finishes.
-You can use this keyword to insert delays between different stages.
-
-The timer of a delayed job starts immediately after the previous stage completes.
-Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passes.
+1. Executes `cleanup_build_job` only when `build_job` fails.
+1. Always executes `cleanup_job` as the last step in pipeline regardless of
+   success or failure.
+1. Executes `deploy_job` when you run it manually in the GitLab UI.
 
-The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage completes:
+**Additional details**:
 
-```yaml
-timed rollout 10%:
-  stage: deploy
-  script: echo 'Rolling out 10% ...'
-  when: delayed
-  start_in: 30 minutes
-```
+- In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you
+  can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and
+  earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`.
+- The default behavior of `allow_failure` changes to `true` with `when: manual`.
+  However, if you use `when: manual` with [`rules`](#rules), `allow_failure` defaults
+  to `false`.
 
-To stop the active timer of a delayed job, click the **{time-out}** (**Unschedule**) button.
-This job can no longer be scheduled to run automatically. You can, however, execute the job manually.
+**Related topics**:
 
-To start a delayed job immediately, click the **Play** button.
-Soon GitLab Runner picks up and starts the job.
+- `when` can be used with [`rules`](#rules) for more dynamic job control.
+- `when` can be used with [`workflow`](#workflow) to control when a pipeline can start.
 
 ### `environment`
 
@@ -2225,11 +2155,11 @@ In the above example, the `review_app` job deploys to the `review`
 environment. A new `stop_review_app` job is listed under `on_stop`.
 After the `review_app` job is finished, it triggers the
 `stop_review_app` job based on what is defined under `when`. In this case,
-it is set to `manual`, so it needs a [manual action](#whenmanual) from
+it is set to `manual`, so it needs a [manual action](../jobs/job_control.md#create-a-job-that-must-be-run-manually) from
 the GitLab UI to run.
 
 Also in the example, `GIT_STRATEGY` is set to `none`. If the
-`stop_review_app` job is [automatically triggered](../environments/index.md#stopping-an-environment),
+`stop_review_app` job is [automatically triggered](../environments/index.md#stop-an-environment),
 the runner won't try to check out the code after the branch is deleted.
 
 The example also overwrites global variables. If your `stop` `environment` job depends
@@ -3262,7 +3192,7 @@ dashboards.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0.
 > - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above.
 
-The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/mr_integration.md#setup). The collected Terraform
+The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform
 plan report uploads to GitLab as an artifact and displays
 in merge requests. For more information, see
 [Output `terraform plan` information into a merge request](../../user/infrastructure/mr_integration.md).
@@ -3346,6 +3276,50 @@ Coverage output from [child pipelines](../pipelines/parent_child_pipelines.md) i
 or displayed. Check [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/280818)
 for more details.
 
+### `dast_configuration` **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5981) in GitLab 14.1.
+
+Use the `dast_configuration` keyword to specify a site profile and scanner profile to be used in a
+CI/CD configuration. Both profiles must first have been created in the project. The job's stage must
+be `dast`.
+
+**Keyword type**: Job keyword. You can use only as part of a job.
+
+**Possible inputs**: One each of `site_profile` and `scanner_profile`.
+
+- Use `site_profile` to specify the site profile to be used in the job.
+- Use `scanner_profile` to specify the scanner profile to be used in the job.
+
+**Example of `dast_configuration`**:
+
+```yaml
+stages:
+  - build
+  - dast
+
+include:
+  - template: DAST.gitlab-ci.yml
+
+dast:
+  dast_configuration:
+    site_profile: "Example Co"
+    scanner_profile: "Quick Passive Test"
+```
+
+In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword
+to select a specific site profile and scanner profile.
+
+**Additional details**:
+
+- Settings contained in either a site profile or scanner profile take precedence over those
+  contained in the DAST template.
+
+**Related topics**:
+
+- [Site profile](../../user/application_security/dast/index.md#site-profile).
+- [Scanner profile](../../user/application_security/dast/index.md#scanner-profile).
+
 ### `retry`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) in GitLab 11.5, you can control which failures to retry on.
@@ -3500,7 +3474,7 @@ but with different variable values for each instance of the job.
 There can be from 2 to 50 jobs.
 
 Jobs can only run in parallel if there are multiple runners, or a single runner is
-[configured to run multiple jobs concurrently](#use-your-own-runners).
+configured to run multiple jobs concurrently.
 
 Every job gets the same `CI_NODE_TOTAL` [CI/CD variable](../variables/index.md#predefined-cicd-variables) value, and a unique `CI_NODE_INDEX` value.
 
@@ -3590,6 +3564,23 @@ deploystacks: [gcp, data]
 deploystacks: [vultr, data]
 ```
 
+In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/239737), you can
+use the variables defined in `parallel: matrix` with the [`tags`](#tags) keyword for
+dynamic runner selection.
+
+```yaml
+deploystacks:
+  stage: deploy
+  parallel:
+    matrix:
+      - PROVIDER: aws
+        STACK: [monitoring, app1]
+      - PROVIDER: gcp
+        STACK: [data]
+  tags:
+    - ${PROVIDER}-${STACK}
+```
+
 ### `trigger`
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
@@ -3612,7 +3603,7 @@ view which job triggered a downstream pipeline. In the [pipeline graph](../pipel
 hover over the downstream pipeline job.
 
 In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you
-can use [`when:manual`](#whenmanual) in the same job as `trigger`. In GitLab 13.4 and
+can use [`when:manual`](#when) in the same job as `trigger`. In GitLab 13.4 and
 earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`.
 You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086).
 
@@ -3931,19 +3922,28 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest
 
 #### `release-cli` for shell executors
 
-> [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8.
+> - [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): the `release-cli` binaries are also
+[available in the Package Registry](https://gitlab.com/jaime/release-cli/-/packages)
+starting from GitLab 14.2.
 
 For GitLab Runner shell executors, 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 should be available to you.
 
 **Install on Unix/Linux**
 
-1. Download the binary for your system, in the following example for amd64 systems:
+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
@@ -4527,50 +4527,6 @@ You can use [CI/CD variables](../variables/index.md) to configure how the runner
 You can also use variables to configure how many times a runner
 [attempts certain stages of job execution](../runners/configure_runners.md#job-stages-attempts).
 
-## `dast_configuration` **(ULTIMATE)**
-
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5981) in GitLab 14.1.
-
-Use the `dast_configuration` keyword to specify a site profile and scanner profile to be used in a
-CI/CD configuration. Both profiles must first have been created in the project. The job's stage must
-be `dast`.
-
-**Keyword type**: Job keyword. You can use only as part of a job.
-
-**Possible inputs**: One each of `site_profile` and `scanner_profile`.
-
-- Use `site_profile` to specify the site profile to be used in the job.
-- Use `scanner_profile` to specify the scanner profile to be used in the job.
-
-**Example of `dast_configuration`**:
-
-```yaml
-stages:
-  - build
-  - dast
-
-include:
-  - template: DAST.gitlab-ci.yml
-
-dast:
-  dast_configuration:
-    site_profile: "Example Co"
-    scanner_profile: "Quick Passive Test"
-```
-
-In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword
-to select a specific site profile and scanner profile.
-
-**Additional details**:
-
-- Settings contained in either a site profile or scanner profile take precedence over those
-  contained in the DAST template.
-
-**Related topics**:
-
-- [Site profile](../../user/application_security/dast/index.md#site-profile).
-- [Scanner profile](../../user/application_security/dast/index.md#scanner-profile).
-
 ## YAML-specific features
 
 In your `.gitlab-ci.yml` file, you can use YAML-specific features like anchors (`&`), aliases (`*`),
diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md
index 9e118895d7c..93c1a6afe69 100644
--- a/doc/ci/yaml/script.md
+++ b/doc/ci/yaml/script.md
@@ -14,6 +14,85 @@ You can use special syntax in [`script`](index.md#script) sections to:
 - [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections)
   to simplify job log output.
 
+## Use special characters with `script:`
+
+Sometimes, `script` commands must be wrapped in single or double quotes.
+For example, commands that contain a colon (`:`) must be wrapped in single quotes (`'`).
+The YAML parser needs to interpret the text as a string rather than
+a "key: value" pair.
+
+For example, this script uses a colon:
+
+```yaml
+job:
+  script:
+    - curl --request POST --header 'Content-Type: application/json' "https://gitlab/api/v4/projects"
+```
+
+To be considered valid YAML, you must wrap the entire command in single quotes. If
+the command already uses single quotes, you should change them to double quotes (`"`)
+if possible:
+
+```yaml
+job:
+  script:
+    - 'curl --request POST --header "Content-Type: application/json" "https://gitlab/api/v4/projects"'
+```
+
+You can verify the syntax is valid with the [CI Lint](../lint.md) tool.
+
+Be careful when using these characters as well:
+
+- `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
+
+## Ignore non-zero exit codes
+
+When script commands return an exit code other than zero, the job fails and further
+commands do not execute.
+
+Store the exit code in a variable to avoid this behavior:
+
+```yaml
+job:
+  script:
+    - false || exit_code=$?
+    - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;
+```
+
+## Set a default `before_script` or `after_script` for all jobs
+
+You can use [`before_script`](index.md#before_script) and [`after_script`](index.md#after_script)
+with [`default`](index.md#custom-default-keyword-values):
+
+- Use `before_script` with `default` to define a default array of commands that
+  should run before the `script` commands in all jobs.
+- Use `after_script` with default to define a default array of commands
+  that should run after the job completes.
+
+You can overwrite a default by defining a different one in a job. To ignore the default
+use `before_script: []` or `after_script: []`:
+
+```yaml
+default:
+  before_script:
+    - echo "Execute this `before_script` in all jobs by default."
+  after_script:
+    - echo "Execute this `after_script` in all jobs by default."
+
+job1:
+  script:
+    - echo "These script commands execute after the default `before_script`,"
+    - echo "and before the default `after_script`."
+
+job2:
+  before_script:
+    - echo "Execute this script instead of the default `before_script`."
+  script:
+    - echo "This script executes after the job's `before_script`,"
+    - echo "but the job does not use the default `after_script`."
+  after_script: []
+```
+
 ## Split long commands
 
 You can split long commands into multiline commands to improve readability with