Add latest changes from gitlab-org/gitlab@master

9 files changed, 2372 insertions, 2128 deletions

diff --git a/.gitlab/issue_templates/UX Issue.md b/.gitlab/issue_templates/UX Issue.md
new file mode 100644
index 00000000000..97f3782c4df
--- /dev/null
+++ b/.gitlab/issue_templates/UX Issue.md
@@ -0,0 +1,58 @@
+<!-- This issue template can be used as a starting point for a UX Issue. This is not a feature request, rather an issue that is being created for a product designer to solve a problem.
+
+The goal of this template is to ensure we have captured all the information available to the product designer so they can approach the problem creatively and efficiently. Please add links to SSOT if this informatin exists elsewhere. -->
+
+### Who will use this solution? 
+
+<!-- If known, include any of the following: types of users (e.g. Developer), personas, or specific company roles (e.g. Release Manager). It's okay to write "Unknown" and fill this field in later.
+
+Personas are described at https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/
+
+* [Cameron (Compliance Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#cameron-compliance-manager)
+* [Parker (Product Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#parker-product-manager)
+* [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead)
+* [Presley (Product Designer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#presley-product-designer)
+* [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer)
+* [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer)
+* [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator)
+* [Sam (Security Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sam-security-analyst)
+* [Rachel (Release Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#rachel-release-manager)
+* [Alex (Security Operations Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#alex-security-operations-engineer)
+* [Simone (Software Engineer in Test)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#simone-software-engineer-in-test)
+* [Allison (Application Ops)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#allison-application-ops)
+* [Priyanka (Platform Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#priyanka-platform-engineer)
+* [Dana (Data Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#dana-data-analyst)
+* [Eddie (Content Editor)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#eddie-content-editor)
+
+-->
+
+
+### What problem do they have?
+
+
+### When do they have the problem?
+
+
+### Where in the app do they have the problem and at what frequency (if known)?
+
+
+### Why will a design help them?
+
+
+### What is the JTBD and/or Tasks?
+
+
+### Is this problem supported by user research (please link relevant research issue/s)?
+
+
+### Known technical constraints
+
+
+### How does this help the business?
+
+
+
+
+
+/label ~"group::" ~"section::"  ~"Category::"  ~UX 
+
diff --git a/GITALY_SERVER_VERSION b/GITALY_SERVER_VERSION
index df08b18725a..447fd9d98b9 100644
--- a/GITALY_SERVER_VERSION
+++ b/GITALY_SERVER_VERSION
@@ -1 +1 @@
-37118baf7b10c95f533230797d849d2251805236
+b6dda5d1f7a7e05c34ed0f72f161a46aee536d75
\ No newline at end of file
diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md
index 903881497dd..fe6844b89a2 100644
--- a/doc/ci/environments/index.md
+++ b/doc/ci/environments/index.md
@@ -447,6 +447,63 @@ try to check out the code after the branch is deleted.
 
 Read more in the [`.gitlab-ci.yml` reference](../yaml/index.md#environmenton_stop).
 
+#### Stop an environment when another job is finished
+
+You can set an environment to stop when another job is finished.
+
+In your `.gitlab-ci.yml` file, specify in the [`on_stop:`](../yaml/index.md#environmenton_stop)
+keyword the name of the job that stops the environment.
+
+The following example shows a `review_app` job that calls a `stop_review_app` job after the first
+job is finished. The `stop_review_app` is triggered based on what is defined under `when`. In this
+case, 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.
+
+Both jobs must have the same rules or only/except configuration.
+In this example, if the configuration is not identical:
+
+- The `stop_review_app` job might not be included in all pipelines that include the `review_app` job.
+- It is not possible to trigger the `action: stop` to stop the environment automatically.
+
+Also in the example, `GIT_STRATEGY` is set to `none`. If the
+`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
+on global variables, use [anchor variables](../yaml/yaml_optimization.md#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`
+to change the job without overriding the global variables.
+
+The `stop_review_app` job **must** have the following keywords defined:
+
+- `when`, defined at either:
+  - [The job level](../yaml/index.md#when).
+  - [In a rules clause](../yaml/index.md#rules). If you use `rules:` and `when: manual`, you should
+    also set [`allow_failure: true`](../yaml/index.md#allow_failure) so the pipeline can complete
+    even if the job doesn't run.
+- `environment:name`
+- `environment:action`
+
+```yaml
+review_app:
+  stage: deploy
+  script: make deploy-app
+  environment:
+    name: review/$CI_COMMIT_REF_SLUG
+    url: https://$CI_ENVIRONMENT_SLUG.example.com
+    on_stop: stop_review_app
+
+stop_review_app:
+  stage: deploy
+  variables:
+    GIT_STRATEGY: none
+  script: make delete-app
+  when: manual
+  environment:
+    name: review/$CI_COMMIT_REF_SLUG
+    action: stop
+```
+
 #### Stop an environment after a certain time period
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index feb70765bda..31300276e7b 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -25,9 +25,9 @@ A GitLab CI/CD pipeline configuration includes:
   | Keyword                 | Description |
   |-------------------------|:------------|
   | [`default`](#default)   | Custom default values for job keywords. |
+  | [`include`](#include)   | Import configuration from other YAML files. |
   | [`stages`](#stages)     | The names and order of the pipeline stages. |
   | [`workflow`](#workflow) | Control what types of pipeline run. |
-  | [`include`](#include)   | Import configuration from other YAML files. |
 
 - [Jobs](../jobs/index.md) configured with [job keywords](#job-keywords):
 
@@ -116,179 +116,6 @@ a job-specific `image:` section:
   takes precedence and is not replaced by the default.
 - Control inheritance of default keywords in jobs with [`inherit:default`](#inheritdefault).
 
-### `stages`
-
-Use `stages` to define stages that contain groups of jobs. Use [`stage`](#stage)
-in a job to configure the job to run in a specific stage.
-
-If `stages` is not defined in the `.gitlab-ci.yml` file, the default pipeline stages are:
-
-- [`.pre`](#stage-pre)
-- `build`
-- `test`
-- `deploy`
-- [`.post`](#stage-post)
-
-The order of the items in `stages` defines the execution order for jobs:
-
-- Jobs in the same stage run in parallel.
-- Jobs in the next stage run after the jobs from the previous stage complete successfully.
-
-**Keyword type**: Global keyword.
-
-**Example of `stages`:**
-
-```yaml
-stages:
-  - build
-  - test
-  - deploy
-```
-
-In this example:
-
-1. All jobs in `build` execute in parallel.
-1. If all jobs in `build` succeed, the `test` jobs execute in parallel.
-1. If all jobs in `test` succeed, the `deploy` jobs execute in parallel.
-1. If all jobs in `deploy` succeed, the pipeline is marked as `passed`.
-
-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.
-
-**Additional details**:
-
-- 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,
-  which can help [compliance pipeline configurations](../../user/project/settings/index.md#compliance-pipeline-configuration):
-  - Stages can be defined in the compliance configuration but remain hidden if not used.
-  - The defined stages become visible when developers use them in job definitions.
-
-**Related topics**:
-
-- To make a job start earlier and ignore the stage order, use the [`needs`](#needs) keyword.
-
-### `workflow`
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5
-
-Use [`workflow`](workflow.md) to control pipeline behavior.
-
-**Related topics**:
-
-- [`workflow: rules` examples](workflow.md#workflow-rules-examples)
-- [Switch between branch pipelines and merge request pipelines](workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines)
-
-#### `workflow:rules`
-
-The `rules` keyword in `workflow` is similar to [`rules:` defined in jobs](#rules),
-but controls whether or not a whole pipeline is created.
-
-When no rules evaluate to true, the pipeline does not run.
-
-**Possible inputs**: You can use some of the same keywords as job-level [`rules`](#rules):
-
-- [`rules: if`](#rulesif).
-- [`rules: changes`](#ruleschanges).
-- [`rules: exists`](#rulesexists).
-- [`when`](#when), can only be `always` or `never` when used with `workflow`.
-- [`variables`](#workflowrulesvariables).
-
-**Example of `workflow:rules`:**
-
-```yaml
-workflow:
-  rules:
-    - if: $CI_COMMIT_MESSAGE =~ /-draft$/
-      when: never
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-```
-
-In this example, pipelines run if the commit message does not have `-drafts` in it
-and the pipeline is for either:
-
-- A merge request
-- The default branch.
-
-**Additional details**:
-
-- If your rules match both branch pipelines (other than the default branch) and merge request pipelines,
-  [duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines) can occur.
-
-**Related topics**:
-
-- You can use the [`workflow:rules` templates](workflow.md#workflowrules-templates) to import
-  a preconfigured `workflow: rules` entry.
-- [Common `if` clauses for `workflow:rules`](workflow.md#common-if-clauses-for-workflowrules).
-
-#### `workflow:rules:variables`
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/300997) in GitLab 14.1.
-
-You can use [`variables`](#variables) in `workflow:rules:` to define variables for
-specific pipeline conditions.
-
-When the condition matches, the variable is created and can be used by all jobs
-in the pipeline. If the variable is already defined at the global level, the `workflow`
-variable takes precedence and overrides the global variable.
-
-**Keyword type**: Global keyword.
-
-**Possible inputs**: Variable name and value pairs:
-
-- The name can use only numbers, letters, and underscores (`_`).
-- The value must be a string.
-
-**Example of `workflow:rules:variables`:**
-
-```yaml
-variables:
-  DEPLOY_VARIABLE: "default-deploy"
-
-workflow:
-  rules:
-    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
-      variables:
-        DEPLOY_VARIABLE: "deploy-production"  # Override globally-defined DEPLOY_VARIABLE
-    - if: $CI_COMMIT_REF_NAME =~ /feature/
-      variables:
-        IS_A_FEATURE: "true"                  # Define a new variable.
-    - when: always                            # Run the pipeline in other cases
-
-job1:
-  variables:
-    DEPLOY_VARIABLE: "job1-default-deploy"
-  rules:
-    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
-      variables:                                   # Override DEPLOY_VARIABLE defined
-        DEPLOY_VARIABLE: "job1-deploy-production"  # at the job level.
-    - when: on_success                             # Run the job in other cases
-  script:
-    - echo "Run script with $DEPLOY_VARIABLE as an argument"
-    - echo "Run another script if $IS_A_FEATURE exists"
-
-job2:
-  script:
-    - echo "Run script with $DEPLOY_VARIABLE as an argument"
-    - echo "Run another script if $IS_A_FEATURE exists"
-```
-
-When the branch is the default branch:
-
-- job1's `DEPLOY_VARIABLE` is `job1-deploy-production`.
-- job2's `DEPLOY_VARIABLE` is `deploy-production`.
-
-When the branch is `feature`:
-
-- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`, and `IS_A_FEATURE` is `true`.
-- job2's `DEPLOY_VARIABLE` is `default-deploy`, and `IS_A_FEATURE` is `true`.
-
-When the branch is something else:
-
-- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`.
-- job2's `DEPLOY_VARIABLE` is `default-deploy`.
-
 ### `include`
 
 > [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4.
@@ -477,219 +304,184 @@ include:
 - All [nested includes](includes.md#use-nested-includes) are executed only with the permission of the user,
   so it's possible to use `project`, `remote`, or `template` includes.
 
-## Job keywords
+### `stages`
 
-The following topics explain how to use keywords to configure CI/CD pipelines.
+Use `stages` to define stages that contain groups of jobs. Use [`stage`](#stage)
+in a job to configure the job to run in a specific stage.
 
-### `image`
+If `stages` is not defined in the `.gitlab-ci.yml` file, the default pipeline stages are:
 
-Use `image` to specify a Docker image that the job runs in.
+- [`.pre`](#stage-pre)
+- `build`
+- `test`
+- `deploy`
+- [`.post`](#stage-post)
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+The order of the items in `stages` defines the execution order for jobs:
 
-**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats:
+- Jobs in the same stage run in parallel.
+- Jobs in the next stage run after the jobs from the previous stage complete successfully.
 
-- `<image-name>` (Same as using `<image-name>` with the `latest` tag)
-- `<image-name>:<tag>`
-- `<image-name>@<digest>`
+**Keyword type**: Global keyword.
 
-**Example of `image`**:
+**Example of `stages`:**
 
 ```yaml
-default:
-  image: ruby:3.0
-
-rspec:
-  script: bundle exec rspec
-
-rspec 2.7:
-  image: registry.example.com/my-group/my-project/ruby:2.7
-  script: bundle exec rspec
+stages:
+  - build
+  - test
+  - deploy
 ```
 
-In this example, the `ruby:3.0` image is the default for all jobs in the pipeline.
-The `rspec 2.7` job does not use the default, because it overrides the default with
-a job-specific `image:` section.
+In this example:
 
-**Related topics**:
+1. All jobs in `build` execute in parallel.
+1. If all jobs in `build` succeed, the `test` jobs execute in parallel.
+1. If all jobs in `test` succeed, the `deploy` jobs execute in parallel.
+1. If all jobs in `deploy` succeed, the pipeline is marked as `passed`.
 
-- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md).
+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.
 
-#### `image:name`
+**Additional details**:
 
-The name of the Docker image that the job runs in. Similar to [`image:`](#image) used by itself.
+- 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,
+  which can help [compliance pipeline configurations](../../user/project/settings/index.md#compliance-pipeline-configuration):
+  - Stages can be defined in the compliance configuration but remain hidden if not used.
+  - The defined stages become visible when developers use them in job definitions.
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+**Related topics**:
 
-**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats:
+- To make a job start earlier and ignore the stage order, use the [`needs`](#needs) keyword.
 
-- `<image-name>` (Same as using `<image-name>` with the `latest` tag)
-- `<image-name>:<tag>`
-- `<image-name>@<digest>`
+### `workflow`
 
-**Example of `image:name`**:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5
 
-```yaml
-image:
-  name: "registry.example.com/my/image:latest"
-```
+Use [`workflow`](workflow.md) to control pipeline behavior.
 
 **Related topics**:
 
-- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md).
+- [`workflow: rules` examples](workflow.md#workflow-rules-examples)
+- [Switch between branch pipelines and merge request pipelines](workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines)
 
-#### `image:entrypoint`
+#### `workflow:rules`
 
-Command or script to execute as the container's entry point.
+The `rules` keyword in `workflow` is similar to [`rules:` defined in jobs](#rules),
+but controls whether or not a whole pipeline is created.
 
-When the Docker container is created, the `entrypoint` is translated to the Docker `--entrypoint` option.
-The syntax is similar to the [Dockerfile `ENTRYPOINT` directive](https://docs.docker.com/engine/reference/builder/#entrypoint),
-where each shell token is a separate string in the array.
+When no rules evaluate to true, the pipeline does not run.
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+**Possible inputs**: You can use some of the same keywords as job-level [`rules`](#rules):
 
-**Possible inputs**: A string.
+- [`rules: if`](#rulesif).
+- [`rules: changes`](#ruleschanges).
+- [`rules: exists`](#rulesexists).
+- [`when`](#when), can only be `always` or `never` when used with `workflow`.
+- [`variables`](#workflowrulesvariables).
 
-**Example of `image:entrypoint`**:
+**Example of `workflow:rules`:**
 
 ```yaml
-image:
-  name: super/sql:experimental
-  entrypoint: [""]
+workflow:
+  rules:
+    - if: $CI_COMMIT_MESSAGE =~ /-draft$/
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 ```
 
-**Related topics**:
-
-- [Override the entrypoint of an image](../docker/using_docker_images.md#override-the-entrypoint-of-an-image).
-
-#### `services`
-
-Use `services` to specify an additional Docker image to run scripts in. The [`services` image](../services/index.md) is linked
-to the image specified in the [`image`](#image) keyword.
-
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
-
-**Possible inputs**: The name of the services image, including the registry path if needed, in one of these formats:
-
-- `<image-name>` (Same as using `<image-name>` with the `latest` tag)
-- `<image-name>:<tag>`
-- `<image-name>@<digest>`
+In this example, pipelines run if the commit message does not have `-drafts` in it
+and the pipeline is for either:
 
-**Example of `services`**:
+- A merge request
+- The default branch.
 
-```yaml
-default:
-  image:
-    name: ruby:2.6
-    entrypoint: ["/bin/bash"]
+**Additional details**:
 
-  services:
-    - name: my-postgres:11.7
-      alias: db-postgres
-      entrypoint: ["/usr/local/bin/db-postgres"]
-      command: ["start"]
+- If your rules match both branch pipelines (other than the default branch) and merge request pipelines,
+  [duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines) can occur.
 
-  before_script:
-    - bundle install
+**Related topics**:
 
-test:
-  script:
-    - bundle exec rake spec
-```
+- You can use the [`workflow:rules` templates](workflow.md#workflowrules-templates) to import
+  a preconfigured `workflow: rules` entry.
+- [Common `if` clauses for `workflow:rules`](workflow.md#common-if-clauses-for-workflowrules).
 
-In this example, the job launches a Ruby container. Then, from that container, the job launches
-another container that's running PostgreSQL. Then the job then runs scripts
-in that container.
+#### `workflow:rules:variables`
 
-**Related topics**:
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/300997) in GitLab 14.1.
 
-- [Available settings for `services`](../services/index.md#available-settings-for-services).
-- [Define `services` in the `.gitlab-ci.yml` file](../services/index.md#define-services-in-the-gitlab-ciyml-file).
-- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md).
-- [Use Docker to build Docker images](../docker/using_docker_build.md).
+You can use [`variables`](#variables) in `workflow:rules:` to define variables for
+specific pipeline conditions.
 
-### `script`
+When the condition matches, the variable is created and can be used by all jobs
+in the pipeline. If the variable is already defined at the global level, the `workflow`
+variable takes precedence and overrides the global variable.
 
-Use `script` to specify commands for the runner to execute.
+**Keyword type**: Global keyword.
 
-All jobs except [trigger jobs](#trigger) require a `script` keyword.
+**Possible inputs**: Variable name and value pairs:
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+- The name can use only numbers, letters, and underscores (`_`).
+- The value must be a string.
 
-**Possible inputs**: An array including:
+**Example of `workflow:rules:variables`:**
 
-- Single line commands.
-- Long commands [split over multiple lines](script.md#split-long-commands).
-- [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts).
+```yaml
+variables:
+  DEPLOY_VARIABLE: "default-deploy"
 
-**Example of `script`:**
+workflow:
+  rules:
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+      variables:
+        DEPLOY_VARIABLE: "deploy-production"  # Override globally-defined DEPLOY_VARIABLE
+    - if: $CI_COMMIT_REF_NAME =~ /feature/
+      variables:
+        IS_A_FEATURE: "true"                  # Define a new variable.
+    - when: always                            # Run the pipeline in other cases
 
-```yaml
 job1:
-  script: "bundle exec rspec"
+  variables:
+    DEPLOY_VARIABLE: "job1-default-deploy"
+  rules:
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+      variables:                                   # Override DEPLOY_VARIABLE defined
+        DEPLOY_VARIABLE: "job1-deploy-production"  # at the job level.
+    - when: on_success                             # Run the job in other cases
+  script:
+    - echo "Run script with $DEPLOY_VARIABLE as an argument"
+    - echo "Run another script if $IS_A_FEATURE exists"
 
 job2:
   script:
-    - uname -a
-    - bundle exec rspec
+    - echo "Run script with $DEPLOY_VARIABLE as an argument"
+    - echo "Run another script if $IS_A_FEATURE exists"
 ```
 
-**Additional details**:
-
-- When you use [these special characters in `script`](script.md#use-special-characters-with-script), you must use single quotes (`'`) or double quotes (`"`) .
-
-**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.
-
-#### `before_script`
-
-Use `before_script` to define an array of commands that should run before each job's
-`script` commands, but after [artifacts](#artifacts) are restored.
-
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
-
-**Possible inputs**: An array including:
+When the branch is the default branch:
 
-- Single line commands.
-- Long commands [split over multiple lines](script.md#split-long-commands).
-- [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts).
+- job1's `DEPLOY_VARIABLE` is `job1-deploy-production`.
+- job2's `DEPLOY_VARIABLE` is `deploy-production`.
 
-**Example of `before_script`:**
+When the branch is `feature`:
 
-```yaml
-job:
-  before_script:
-    - echo "Execute this command before any 'script:' commands."
-  script:
-    - echo "This command executes after the job's 'before_script' commands."
-```
+- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`, and `IS_A_FEATURE` is `true`.
+- job2's `DEPLOY_VARIABLE` is `default-deploy`, and `IS_A_FEATURE` is `true`.
 
-**Additional details**:
+When the branch is something else:
 
-- Scripts you specify in `before_script` are concatenated with any scripts you specify
-  in the main [`script`](#script). The combined scripts execute together in a single shell.
+- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`.
+- job2's `DEPLOY_VARIABLE` is `default-deploy`.
 
-**Related topics**:
+## Job keywords
 
-- [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.
+The following topics explain how to use keywords to configure CI/CD pipelines.
 
-#### `after_script`
+### `after_script`
 
 Use `after_script` to define an array of commands that run after each job, including failed jobs.
 
@@ -740,1168 +532,967 @@ If a job times out or is cancelled, the `after_script` commands do not execute.
 - [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections)
   to simplify job log output.
 
-### `stage`
+### `allow_failure`
 
-Use `stage` to define which [stage](#stages) a job runs in. Jobs in the same
-`stage` can execute in parallel (see **Additional details**).
+Use `allow_failure` to determine whether a pipeline should continue running when a job fails.
 
-If `stage` is not defined, the job uses the `test` stage by default.
+- To let the pipeline continue running subsequent jobs, use `allow_failure: true`.
+- To stop the pipeline from running subsequent jobs, use `allow_failure: false`.
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+When jobs are allowed to fail (`allow_failure: true`) an orange warning (**{status_warning}**)
+indicates that a job failed. However, the pipeline is successful and the associated commit
+is marked as passed with no warnings.
 
-**Possible inputs**: An array including any number of stage names. Stage names can be:
+This same warning is displayed when:
 
-- The [default stages](#stages).
-- User-defined stages.
+- All other jobs in the stage are successful.
+- All other jobs in the pipeline are successful.
 
-**Example of `stage`**:
+The default value for `allow_failure` is:
 
-```yaml
-stages:
-  - build
-  - test
-  - deploy
+- `true` for [manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually).
+- `false` for manual jobs that also use [`rules`](#rules).
+- `false` in all other cases.
 
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: `true` or `false`.
+
+**Example of `allow_failure`**:
+
+```yaml
 job1:
-  stage: build
+  stage: test
   script:
-    - echo "This job compiles code."
+    - execute_script_1
 
 job2:
   stage: test
   script:
-    - echo "This job tests the compiled code. It runs when the build stage completes."
+    - execute_script_2
+  allow_failure: true
 
 job3:
-  script:
-    - echo "This job also runs in the test stage".
-
-job4:
   stage: deploy
   script:
-    - echo "This job deploys the code. It runs when the test stage completes."
+    - deploy_to_staging
 ```
 
-**Additional details**:
+In this example, `job1` and `job2` run in parallel:
 
-- 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`.
+- If `job1` fails, jobs in the `deploy` stage do not start.
+- If `job2` fails, jobs in the `deploy` stage can still start.
 
-#### `stage: .pre`
+**Additional details**:
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4.
+- You can use `allow_failure` as a subkey of [`rules:`](#rulesallow_failure).
+- You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs).
+  A blocked pipeline does not run any jobs in later stages until the manual job
+  is started and completes successfully.
 
-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 have to define `.pre` in [`stages`](#stages).
+#### `allow_failure:exit_codes`
 
-You must have a job in at least one stage other than `.pre` or `.post`.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) in GitLab 13.8.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) in GitLab 13.9.
 
-**Keyword type**: You can only use it with a job's `stage` keyword.
+Use `allow_failure:exit_codes` to control when a job should be
+allowed to fail. The job is `allow_failure: true` for any of the listed exit codes,
+and `allow_failure` false for any other exit code.
 
-**Example of `stage: .pre`**:
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-```yaml
-stages:
-  - build
-  - test
+**Possible inputs**:
 
-job1:
-  stage: build
-  script:
-    - echo "This job runs in the build stage."
+- A single exit code.
+- An array of exit codes.
 
-first-job:
-  stage: .pre
+**Example of `allow_failure`**:
+
+```yaml
+test_job_1:
   script:
-    - echo "This job runs in the .pre stage, before all other stages."
+    - echo "Run a script that results in exit code 1. This job fails."
+    - exit 1
+  allow_failure:
+    exit_codes: 137
 
-job2:
-  stage: test
+test_job_2:
   script:
-    - echo "This job runs in the test stage."
+    - echo "Run a script that results in exit code 137. This job is allowed to fail."
+    - exit 137
+  allow_failure:
+    exit_codes:
+      - 137
+      - 255
 ```
 
-#### `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 have 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.
+### `artifacts`
 
-**Example of `stage: .post`**:
+Use `artifacts` to specify a list of files and directories that are
+attached to the job when it [succeeds, fails, or always](#artifactswhen).
 
-```yaml
-stages:
-  - build
-  - test
+The artifacts are sent to GitLab after the job finishes. They are
+available for download in the GitLab UI if the size is not
+larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd).
 
-job1:
-  stage: build
-  script:
-    - echo "This job runs in the build stage."
+By default, jobs in later stages automatically download all the artifacts created
+by jobs in earlier stages. You can control artifact download behavior in jobs with
+[`dependencies`](#dependencies).
 
-last-job:
-  stage: .post
-  script:
-    - echo "This job runs in the .post stage, after all other stages."
+When using the [`needs`](#needs) keyword, jobs can only download
+artifacts from the jobs defined in the `needs` configuration.
 
-job2:
-  stage: test
-  script:
-    - echo "This job runs in the test stage."
-```
+Job artifacts are only collected for successful jobs by default, and
+artifacts are restored after [caches](#cache).
 
-### `extends`
+[Read more about artifacts](../pipelines/job_artifacts.md).
 
-Use `extends` to reuse configuration sections. It's an alternative to [YAML anchors](yaml_optimization.md#anchors)
-and is a little more flexible and readable.
+#### `artifacts:exclude`
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) in GitLab 13.1
+> - Requires GitLab Runner 13.1
 
-**Possible inputs:**
+`exclude` makes it possible to prevent files from being added to an artifacts
+archive.
 
-- The name of another job in the pipeline.
-- A list (array) of names of other jobs in the pipeline.
+Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative
+to the project directory. You can use Wildcards that use
+[glob](https://en.wikipedia.org/wiki/Glob_(programming)) or
+[`doublestar.PathMatch`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#PathMatch) patterns.
 
-**Example of `extends`:**
+For example, to store all files in `binaries/`, but not `*.o` files located in
+subdirectories of `binaries/`:
 
 ```yaml
-.tests:
-  script: rake test
-  stage: test
-  only:
-    refs:
-      - branches
-
-rspec:
-  extends: .tests
-  script: rake rspec
-  only:
-    variables:
-      - $RSPEC
+artifacts:
+  paths:
+    - binaries/
+  exclude:
+    - binaries/**/*.o
 ```
 
-In this example, the `rspec` job uses the configuration from the `.tests` template job.
-When creating the pipeline, GitLab:
-
-- Performs a reverse deep merge based on the keys.
-- Merges the `.tests` content with the `rspec` job.
-- Doesn't merge the values of the keys.
+Unlike [`artifacts:paths`](#artifactspaths), `exclude` paths are not recursive. To exclude all of the contents of a directory, you can match them explicitly rather than matching the directory itself.
 
-The result is this `rspec` job:
+For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory:
 
 ```yaml
-rspec:
-  script: rake rspec
-  stage: test
-  only:
-    refs:
-      - branches
-    variables:
-      - $RSPEC
+artifacts:
+  paths:
+    - binaries/
+  exclude:
+    - binaries/temp/**/*
 ```
 
-**Additional details:**
-
-- In GitLab 12.0 and later, you can use multiple parents for `extends`.
-- The `extends` keyword supports up to eleven levels of inheritance, but you should
-  avoid using more than three levels.
-- In the example above, `.tests` is a [hidden job](../jobs/index.md#hide-jobs),
-  but you can extend configuration from regular jobs as well.
-
-**Related topics:**
-
-- [Reuse configuration sections by using `extends`](yaml_optimization.md#use-extends-to-reuse-configuration-sections).
-- Use `extends` to reuse configuration from [included configuration files](yaml_optimization.md#use-extends-and-include-together).
-
-### `rules`
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3.
-
-Use `rules` to include or exclude jobs in pipelines.
-
-Rules are evaluated when the pipeline is created, and evaluated *in order*
-until the first match. When a match is found, the job is either included or excluded from the pipeline,
-depending on the configuration.
-
-You cannot use dotenv variables created in job scripts in rules, because rules are evaluated before any jobs run.
-
-`rules` replaces [`only/except`](#only--except) and they can't be used together
-in the same job. If you configure one job to use both keywords, the GitLab returns
-a `key may not be used with rules` error.
-
-`rules` accepts an array of rules defined with:
-
-- `if`
-- `changes`
-- `exists`
-- `allow_failure`
-- `variables`
-- `when`
-
-You can combine multiple keywords together for [complex rules](../jobs/job_control.md#complex-rules).
-
-The job is added to the pipeline:
-
-- If an `if`, `changes`, or `exists` rule matches and also has `when: on_success` (default),
-  `when: delayed`, or `when: always`.
-- If a rule is reached that is only `when: on_success`, `when: delayed`, or `when: always`.
-
-The job is not added to the pipeline:
-
-- If no rules match.
-- If a rule matches and has `when: never`.
-
-You can use [`!reference` tags](yaml_optimization.md#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs)
-in different jobs.
+Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded using
+`artifacts:exclude` too.
 
-#### `rules:if`
+#### `artifacts:expire_in`
 
-Use `rules:if` clauses to specify when to add a job to a pipeline:
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0 behind a disabled feature flag, the latest job artifacts are kept regardless of expiry time.
+> - [Made default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8, keeping latest job artifacts can be disabled at the project level.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276583) in GitLab 13.9, keeping latest job artifacts can be disabled instance-wide.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321323) in GitLab 13.12, the latest pipeline artifacts are kept regardless of expiry time.
 
-- If an `if` statement is true, add the job to the pipeline.
-- If an `if` statement is true, but it's combined with `when: never`, do not add the job to the pipeline.
-- If no `if` statements are true, do not add the job to the pipeline.
+Use `expire_in` to specify how long [job artifacts](../pipelines/job_artifacts.md) are stored before
+they expire and are deleted. The `expire_in` setting does not affect:
 
-`if:` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md)
-or [custom CI/CD variables](../variables/index.md#custom-cicd-variables).
+- Artifacts from the latest job, unless keeping the latest job artifacts is:
+  - [Disabled at the project level](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs).
+  - [Disabled instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
+- [Pipeline artifacts](../pipelines/pipeline_artifacts.md). You can't specify an expiration date for
+  pipeline artifacts. See [When pipeline artifacts are deleted](../pipelines/pipeline_artifacts.md#when-pipeline-artifacts-are-deleted)
+  for more information.
 
-**Keyword type**: Job-specific and pipeline-specific. You can use it as part of a job
-to configure the job behavior, or with [`workflow`](#workflow) to configure the pipeline behavior.
+The value of `expire_in` is an elapsed time in seconds, unless a unit is provided. Valid values
+include:
 
-**Possible inputs**: A [CI/CD variable expression](../jobs/job_control.md#cicd-variable-expressions).
+- `'42'`
+- `42 seconds`
+- `3 mins 4 sec`
+- `2 hrs 20 min`
+- `2h20min`
+- `6 mos 1 day`
+- `47 yrs 6 mos and 4d`
+- `3 weeks and 2 days`
+- `never`
 
-**Example of `rules:if`**:
+To expire artifacts one week after being uploaded:
 
 ```yaml
 job:
-  script: echo "Hello, Rules!"
-  rules:
-    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH'
-      when: never
-    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/'
-      when: manual
-      allow_failure: true
-    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
+  artifacts:
+    expire_in: 1 week
 ```
 
-**Additional details**:
-
-- If a rule matches and has no `when` defined, the rule uses the `when`
-  defined for the job, which defaults to `on_success` if not defined.
-- You can define `when` once per rule, or once at the job-level, which applies to
-  all rules. You can't mix `when` at the job-level with `when` in rules.
-- Unlike variables in [`script`](../variables/index.md#use-cicd-variables-in-job-scripts)
-  sections, variables in rules expressions are always formatted as `$VARIABLE`.
-  - You can use `rules:if` with `include` to [conditionally include other configuration files](includes.md#use-rules-with-include).
-
-**Related topics**:
+The expiration time period begins when the artifact is uploaded and stored on GitLab. If the expiry
+time is not defined, it defaults to the
+[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration)
+(30 days by default).
 
-- [Common `if` expressions for `rules`](../jobs/job_control.md#common-if-clauses-for-rules).
-- [Avoid duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines).
+To override the expiration date and protect artifacts from being automatically deleted:
 
-#### `rules:changes`
+- Select **Keep** on the job page.
+- [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of
+  `expire_in` to `never`.
 
-Use `rules:changes` to specify when to add a job to a pipeline by checking for changes
-to specific files.
+After their expiry, artifacts are deleted hourly by default (using a cron job), and are not
+accessible anymore.
 
-WARNING:
-You should use `rules: changes` only with **branch pipelines** or **merge request pipelines**.
-You can use `rules: changes` with other pipeline types, but `rules: changes` always
-evaluates to true when there is no Git `push` event. Tag pipelines, scheduled pipelines,
-and so on do **not** have a Git `push` event associated with them. A `rules: changes` job
-is **always** added to those pipelines if there is no `if:` that limits the job to
-branch or merge request pipelines.
+#### `artifacts:expose_as`
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5.
 
-**Possible inputs**: An array of file paths. In GitLab 13.6 and later,
-[file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges).
+Use the `expose_as` keyword to expose [job artifacts](../pipelines/job_artifacts.md)
+in the [merge request](../../user/project/merge_requests/index.md) UI.
 
-**Example of `rules:changes`**:
+For example, to match a single file:
 
 ```yaml
-docker build:
-  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-      changes:
-        - Dockerfile
-      when: manual
-      allow_failure: true
+test:
+  script: ["echo 'test' > file.txt"]
+  artifacts:
+    expose_as: 'artifact 1'
+    paths: ['file.txt']
 ```
 
-- If the pipeline is a merge request pipeline, check `Dockerfile` for changes.
-- If `Dockerfile` has changed, add the job to the pipeline as a manual job, and the pipeline
-  continues running even if the job is not triggered (`allow_failure: true`).
-- If `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`).
-
-**Additional details**:
+With this configuration, GitLab adds a link **artifact 1** to the relevant merge request
+that points to `file1.txt`. To access the link, select **View exposed artifact**
+below the pipeline graph in the merge request overview.
 
-- `rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychanges--exceptchanges).
-- You can use `when: never` to implement a rule similar to [`except:changes`](#onlychanges--exceptchanges).
-- `changes` resolves to `true` if any of the matching files are changed (an `OR` operation).
+An example that matches an entire directory:
 
-#### `rules:exists`
+```yaml
+test:
+  script: ["mkdir test && echo 'test' > test/file.txt"]
+  artifacts:
+    expose_as: 'artifact 1'
+    paths: ['test/']
+```
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4.
+Note the following:
 
-Use `exists` to run a job when certain files exist in the repository.
+- Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`.
+- A maximum of 10 job artifacts per merge request can be exposed.
+- Glob patterns are unsupported.
+- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#download-job-artifacts) if there is more than
+  one file in the directory.
+- For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`,
+  and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is:
+  - Enabled, GitLab automatically renders the artifact.
+  - Not enabled, the file is displayed in the artifacts browser.
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+#### `artifacts:name`
 
-**Possible inputs**: An array of file paths. Paths are relative to the project directory (`$CI_PROJECT_DIR`)
-and can't directly link outside it. File paths can use glob patterns.
+Use the `name` directive to define the name of the created artifacts
+archive. You can specify a unique name for every archive. The `artifacts:name`
+variable can make use of any of the [predefined variables](../variables/index.md).
+The default name is `artifacts`, which becomes `artifacts.zip` when you download it.
 
-**Example of `rules:exists`**:
+To create an archive with a name of the current job:
 
 ```yaml
 job:
-  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
-  rules:
-    - exists:
-        - Dockerfile
+  artifacts:
+    name: "$CI_JOB_NAME"
+    paths:
+      - binaries/
 ```
 
-`job` runs if a `Dockerfile` exists anywhere in the repository.
-
-**Additional details**:
-
-- Glob patterns are interpreted with Ruby [`File.fnmatch`](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch)
-  with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`.
-- For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns or
-  file paths. After the 10,000th check, rules with patterned globs always match.
-  In other words, the `exists` rule always assumes a match in projects with more
-  than 10,000 files.
-- `exists` resolves to `true` if any of the listed files are found (an `OR` operation).
-
-#### `rules:allow_failure`
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8.
-
-Use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail
-without stopping the pipeline.
-
-You can also use `allow_failure: true` with a manual job. The pipeline continues
-running without waiting for the result of the manual job. `allow_failure: false`
-combined with `when: manual` in rules causes the pipeline to wait for the manual
-job to run before continuing.
-
-**Keyword type**: Job keyword. You can use it only as part of a job.
-
-**Possible inputs**: `true` or `false`. Defaults to `false` if not defined.
-
-**Example of `rules:allow_failure`**:
+To create an archive with a name of the current branch or tag including only
+the binaries directory:
 
 ```yaml
 job:
-  script: echo "Hello, Rules!"
-  rules:
-    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
-      when: manual
-      allow_failure: true
+  artifacts:
+    name: "$CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
 ```
 
-If the rule matches, then the job is a manual job with `allow_failure: true`.
-
-**Additional details**:
-
-- The rule-level `rules:allow_failure` overrides the job-level [`allow_failure`](#allow_failure),
-  and only applies when the specific rule triggers the job.
-
-#### `rules:variables`
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209864) in GitLab 13.7.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289803) in GitLab 13.10.
-
-Use [`variables`](#variables) in `rules:` to define variables for specific conditions.
-
-**Keyword type**: Job-specific. You can use it only as part of a job.
-
-**Possible inputs**: A hash of variables in the format `VARIABLE-NAME: value`.
+If your branch-name contains forward slashes
+(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG`
+instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact.
 
-**Example of `rules:variables`**:
+To create an archive with a name of the current job and the current branch or
+tag including only the binaries directory:
 
 ```yaml
 job:
-  variables:
-    DEPLOY_VARIABLE: "default-deploy"
-  rules:
-    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
-      variables:                              # Override DEPLOY_VARIABLE defined
-        DEPLOY_VARIABLE: "deploy-production"  # at the job level.
-    - if: $CI_COMMIT_REF_NAME =~ /feature/
-      variables:
-        IS_A_FEATURE: "true"                  # Define a new variable.
-  script:
-    - echo "Run script with $DEPLOY_VARIABLE as an argument"
-    - echo "Run another script if $IS_A_FEATURE exists"
+  artifacts:
+    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
 ```
 
-### `only` / `except`
-
-NOTE:
-`only` and `except` are not being actively developed. [`rules`](#rules) is the preferred
-keyword to control when to add jobs to pipelines.
-
-You can use `only` and `except` to control when to add jobs to pipelines.
+To create an archive with a name of the current [stage](#stages) and branch name:
 
-- Use `only` to define when a job runs.
-- Use `except` to define when a job **does not** run.
+```yaml
+job:
+  artifacts:
+    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
 
-Four keywords can be used with `only` and `except`:
+---
 
-- [`refs`](#onlyrefs--exceptrefs)
-- [`variables`](#onlyvariables--exceptvariables)
-- [`changes`](#onlychanges--exceptchanges)
-- [`kubernetes`](#onlykubernetes--exceptkubernetes)
+If you use **Windows Batch** to run your shell scripts you must replace
+`$` with `%`:
 
-See [specify when jobs run with `only` and `except`](../jobs/job_control.md#specify-when-jobs-run-with-only-and-except)
-for more details and examples.
+```yaml
+job:
+  artifacts:
+    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
+    paths:
+      - binaries/
+```
 
-#### `only:refs` / `except:refs`
+If you use **Windows PowerShell** to run your shell scripts you must replace
+`$` with `$env:`:
 
-Use the `only:refs` and `except:refs` keywords to control when to add jobs to a
-pipeline based on branch names or pipeline types.
+```yaml
+job:
+  artifacts:
+    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+#### `artifacts:paths`
 
-**Possible inputs**: An array including any number of:
+Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly
+link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
+patterns and:
 
-- Branch names, for example `main` or `my-feature-branch`.
-- [Regular expressions](../jobs/job_control.md#only--except-regex-syntax)
-  that match against branch names, for example `/^feature-.*/`.
-- The following keywords:
+- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620),
+  [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match).
+- In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match).
 
-  | **Value**                | **Description** |
-  | -------------------------|-----------------|
-  | `api`                    | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). |
-  | `branches`               | When the Git reference for a pipeline is a branch. |
-  | `chat`                   | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. |
-  | `external`               | When you use CI services other than GitLab. |
-  | `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). |
-  | `merge_requests`         | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../pipelines/merge_request_pipelines.md), [merged results pipelines](../pipelines/pipelines_for_merged_results.md), and [merge trains](../pipelines/merge_trains.md). |
-  | `pipelines`              | For [multi-project pipelines](../pipelines/multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../pipelines/multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](#trigger) keyword. |
-  | `pushes`                 | For pipelines triggered by a `git push` event, including for branches and tags. |
-  | `schedules`              | For [scheduled pipelines](../pipelines/schedules.md). |
-  | `tags`                   | When the Git reference for a pipeline is a tag. |
-  | `triggers`               | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). |
-  | `web`                    | For pipelines created by selecting **Run pipeline** in the GitLab UI, from the project's **CI/CD > Pipelines** section. |
+To restrict which jobs a specific job fetches artifacts from, see [dependencies](#dependencies).
 
-**Example of `only:refs` and `except:refs`**:
+Send all files in `binaries` and `.config`:
 
 ```yaml
-job1:
-  script: echo
-  only:
-    - main
-    - /^issue-.*$/
-    - merge_requests
-
-job2:
-  script: echo
-  except:
-    - main
-    - /^stable-branch.*$/
-    - schedules
+artifacts:
+  paths:
+    - binaries/
+    - .config
 ```
 
-**Additional details:**
-
-- Scheduled pipelines run on specific branches, so jobs configured with `only: branches`
-  run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches`
-  from running on scheduled pipelines.
-- `only` or `except` used without any other keywords are equivalent to `only: refs`
-  or `except: refs`. For example, the following two jobs configurations have the same
-  behavior:
+To disable artifact passing, define the job with empty [dependencies](#dependencies):
 
-  ```yaml
-  job1:
-    script: echo
-    only:
-      - branches
+```yaml
+job:
+  stage: build
+  script: make build
+  dependencies: []
+```
 
-  job2:
-    script: echo
-    only:
-      refs:
-        - branches
-  ```
+You may want to create artifacts only for tagged releases to avoid filling the
+build server storage with temporary build artifacts.
 
-- If a job does not use `only`, `except`, or [`rules`](#rules), then `only` is set to `branches`
-  and `tags` by default.
+Create artifacts only for tags (`default-job` doesn't create artifacts):
 
-  For example, `job1` and `job2` are equivalent:
+```yaml
+default-job:
+  script:
+    - mvn test -U
+  rules:
+    - if: $CI_COMMIT_BRANCH
 
-  ```yaml
-  job1:
-    script: echo 'test'
+release-job:
+  script:
+    - mvn package -U
+  artifacts:
+    paths:
+      - target/*.war
+  rules:
+    - if: $CI_COMMIT_TAG
+```
 
-  job2:
-    script: echo 'test'
-    only:
-    - branches
-    - tags
-  ```
+You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with `xyz`:
 
-#### `only:variables` / `except:variables`
+```yaml
+job:
+  artifacts:
+    paths:
+      - path/*xyz/*
+```
 
-Use the `only:variables` or `except:variables` keywords to control when to add jobs
-to a pipeline, based on the status of [CI/CD variables](../variables/index.md).
+#### `artifacts:public`
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49775) in GitLab 13.8
+> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
+> - It's disabled on GitLab.com.
+> - It's recommended for production use.
 
-**Possible inputs**: An array of [CI/CD variable expressions](../jobs/job_control.md#cicd-variable-expressions).
+Use `artifacts:public` to determine whether the job artifacts should be
+publicly available.
 
-**Example of `only:variables`**:
+The default for `artifacts:public` is `true` which means that the artifacts in
+public pipelines are available for download by anonymous and guest users:
 
 ```yaml
-deploy:
-  script: cap staging deploy
-  only:
-    variables:
-      - $RELEASE == "staging"
-      - $STAGING
+artifacts:
+  public: true
 ```
 
-**Related topics**:
-
-- [`only:variables` and `except:variables` examples](../jobs/job_control.md#only-variables--except-variables-examples).
-
-#### `only:changes` / `except:changes`
-
-Use the `changes` keyword with `only` to run a job, or with `except` to skip a job,
-when a Git push event modifies a file.
+To deny read access for anonymous and guest users to artifacts in public
+pipelines, set `artifacts:public` to `false`:
 
-Use `changes` in pipelines with the following refs:
+```yaml
+artifacts:
+  public: false
+```
 
-- `branches`
-- `external_pull_requests`
-- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests))
+#### `artifacts:reports`
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+Use [`artifacts:reports`](artifacts_reports.md) to collect artifacts generated by
+included templates in jobs.
 
-**Possible inputs**: An array including any number of:
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-- Paths to files.
-- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory
-  and all its subdirectories, for example `path/to/directory/**/*`.
-- Wildcard ([glob](https://en.wikipedia.org/wiki/Glob_(programming))) paths for all
-  files with the same extension or multiple extensions, for example `*.md` or `path/to/directory/*.{rb,py,sh}`.
-- Wildcard paths to files in the root directory, or all directories, wrapped in double quotes.
-  For example `"*.json"` or `"**/*.json"`.
+**Possible inputs**: See list of available [artifacts reports types](artifacts_reports.md).
 
-**Example of `only:changes`**:
+**Example of `artifacts:reports`**:
 
 ```yaml
-docker build:
-  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
-  only:
-    refs:
-      - branches
-    changes:
-      - Dockerfile
-      - docker/scripts/*
-      - dockerfiles/**/*
-      - more_scripts/*.{rb,py,sh}
-      - "**/*.json"
+rspec:
+  stage: test
+  script:
+    - bundle install
+    - rspec --format RspecJunitFormatter --out rspec.xml
+  artifacts:
+    reports:
+      junit: rspec.xml
 ```
 
 **Additional details**:
 
-- `changes` resolves to `true` if any of the matching files are changed (an `OR` operation).
-- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`,
-  `changes` can't determine if a given file is new or old and always returns `true`.
-- If you use `only: changes` with other refs, jobs ignore the changes and always run.
-- If you use `except: changes` with other refs, jobs ignore the changes and never run.
-
-**Related topics**:
-
-- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples).
-- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds),
-  you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests).
-- Use `changes` with [new branches or tags *without* pipelines for merge requests](../jobs/job_control.md#use-onlychanges-without-pipelines-for-merge-requests).
-- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines).
-
-#### `only:kubernetes` / `except:kubernetes`
-
-Use `only:kubernetes` or `except:kubernetes` to control if jobs are added to the pipeline
-when the Kubernetes service is active in the project.
+- Combining reports in parent pipelines using [artifacts from child pipelines](#needspipelinejob) is
+  not supported. Track progress on adding support in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215725).
+- To be able to browse the report output files, include the [`artifacts:paths`](#artifactspaths) keyword.
+- The test reports are collected regardless of the job results (success or failure).
+  You can use [`artifacts:expire_in`](#artifactsexpire_in) to set up an expiration
+  date for artifacts reports.
 
-**Keyword type**: Job-specific. You can use it only as part of a job.
+#### `artifacts:untracked`
 
-**Possible inputs**: The `kubernetes` strategy accepts only the `active` keyword.
+Use `artifacts:untracked` to add all Git untracked files as artifacts (along
+with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration
+in the repository's `.gitignore` file.
 
-**Example of `only:kubernetes`**:
+Send all Git untracked files:
 
 ```yaml
-deploy:
-  only:
-    kubernetes: active
+artifacts:
+  untracked: true
 ```
 
-In this example, the `deploy` job runs only when the Kubernetes service is active
-in the project.
+Send all Git untracked files and files in `binaries`:
 
-### `needs`
+```yaml
+artifacts:
+  untracked: true
+  paths:
+    - binaries/
+```
 
-> - [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.
+Send all untracked files but [exclude](#artifactsexclude) `*.txt`:
 
-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).
+```yaml
+artifacts:
+  untracked: true
+  exclude:
+    - "*.txt"
+```
 
-You can ignore stage ordering and run some jobs without waiting for others to complete.
-Jobs in multiple stages can run concurrently.
+#### `artifacts:when`
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+Use `artifacts:when` to upload artifacts on job failure or despite the
+failure.
 
-**Possible inputs**:
+`artifacts:when` can be set to one of the following values:
 
-- An array of jobs.
-- An empty array (`[]`), to set the job to start as soon as the pipeline is created.
+1. `on_success` (default): Upload artifacts only when the job succeeds.
+1. `on_failure`: Upload artifacts only when the job fails.
+1. `always`: Always upload artifacts. For example, when
+   [uploading artifacts](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab) required to
+   troubleshoot failing tests.
 
-**Example of `needs`**:
+For example, to upload artifacts only when a job fails:
 
 ```yaml
-linux:build:
-  stage: build
-  script: echo "Building linux..."
+job:
+  artifacts:
+    when: on_failure
+```
 
-mac:build:
-  stage: build
-  script: echo "Building mac..."
+### `before_script`
 
-lint:
-  stage: test
-  needs: []
-  script: echo "Linting..."
+Use `before_script` to define an array of commands that should run before each job's
+`script` commands, but after [artifacts](#artifacts) are restored.
 
-linux:rspec:
-  stage: test
-  needs: ["linux:build"]
-  script: echo "Running rspec on linux..."
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-mac:rspec:
-  stage: test
-  needs: ["mac:build"]
-  script: echo "Running rspec on mac..."
+**Possible inputs**: An array including:
 
-production:
-  stage: deploy
-  script: echo "Running production..."
-```
+- Single line commands.
+- Long commands [split over multiple lines](script.md#split-long-commands).
+- [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts).
 
-This example creates four paths of execution:
+**Example of `before_script`:**
 
-- Linter: The `lint` job runs immediately without waiting for the `build` stage
-  to complete because it has no needs (`needs: []`).
-- Linux path: The `linux:rspec` job runs as soon as the `linux:build`
-  job finishes, without waiting for `mac:build` to finish.
-- macOS path: The `mac:rspec` jobs runs as soon as the `mac:build`
-  job finishes, without waiting for `linux:build` to finish.
-- The `production` job runs as soon as all previous jobs finish:
-  `linux:build`, `linux:rspec`, `mac:build`, `mac:rspec`.
+```yaml
+job:
+  before_script:
+    - echo "Execute this command before any 'script:' commands."
+  script:
+    - echo "This command executes after the job's 'before_script' commands."
+```
 
 **Additional details**:
 
-- The maximum number of jobs that a single job can have in the `needs:` array is limited:
-  - For GitLab.com, the limit is 50. For more information, see our
-    [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541).
-  - For self-managed instances, the default limit is 50. This limit [can be changed](../../administration/cicd.md#set-the-needs-job-limit).
-- If `needs:` refers to a job that uses the [`parallel`](#parallel) keyword,
-  it depends on all jobs created in parallel, not just one job. It also downloads
-  artifacts from all the parallel jobs by default. If the artifacts have the same
-  name, they overwrite each other and only the last one downloaded is saved.
-- 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.
-- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. Stages must be
-  explicitly defined for all jobs that use the `needs:` keyword, or are referenced
-  in a job's `needs:` section.
-- 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.
-
-#### `needs:artifacts`
+- Scripts you specify in `before_script` are concatenated with any scripts you specify
+  in the main [`script`](#script). The combined scripts execute together in a single shell.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.6.
+**Related topics**:
 
-When a job uses `needs`, it no longer downloads all artifacts from previous stages
-by default, because jobs with `needs` can start before earlier stages complete. With
-`needs` you can only download artifacts from the jobs listed in the `needs:` configuration.
+- [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.
 
-Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are
-downloaded in jobs that use `needs`.
+### `cache`
 
-**Keyword type**: Job keyword. You can use it only as part of a job. Must be used with `needs:job`.
+Use `cache` to specify a list of files and directories to
+cache between jobs. You can only use paths that are in the local working copy.
 
-**Possible inputs**:
+Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts).
 
-- `true` (default) or `false`.
+Learn more about caches in [Caching in GitLab CI/CD](../caching/index.md).
 
-**Example of `needs:artifacts`**:
+#### `cache:paths`
 
-```yaml
-test-job1:
-  stage: test
-  needs:
-    - job: build_job1
-      artifacts: true
+Use the `cache:paths` keyword to choose which files or directories to cache.
 
-test-job2:
-  stage: test
-  needs:
-    - job: build_job2
-      artifacts: false
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-test-job3:
-  needs:
-    - job: build_job1
-      artifacts: true
-    - job: build_job2
-    - build_job3
-```
+**Possible inputs**: An array of paths relative to the project directory (`$CI_PROJECT_DIR`).
+You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
+patterns:
 
-In this example:
+- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620),
+[`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match).
+- In GitLab Runner 12.10 and earlier,
+[`filepath.Match`](https://pkg.go.dev/path/filepath#Match).
 
-- The `test-job1` job downloads the `build_job1` artifacts
-- The `test-job2` job does not download the `build_job2` artifacts.
-- The `test-job3` job downloads the artifacts from all three `build_jobs`, because
-  `artifacts:` is `true`, or defaults to `true`, for all three needed jobs.
+**Example of `cache:paths`**:
 
-**Additional details**:
+Cache all files in `binaries` that end in `.apk` and the `.config` file:
 
-- In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword
-  with `needs`.
+```yaml
+rspec:
+  script:
+    - echo "This job uses a cache."
+  cache:
+    key: binaries-cache
+    paths:
+      - binaries/*.apk
+      - .config
+```
 
-#### `needs:project` **(PREMIUM)**
+**Related topics**:
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.7.
+- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more
+  `cache:paths` examples.
 
-Use `needs:project` to download artifacts from up to five jobs in other pipelines.
-The artifacts are downloaded from the latest successful pipeline for the specified ref.
+#### `cache:key`
 
-If there is a pipeline running for the specified ref, a job with `needs:project`
-does not wait for the pipeline to complete. Instead, the job downloads the artifact
-from the latest pipeline that completed successfully.
+Use the `cache:key` keyword to give each cache a unique identifying key. All jobs
+that use the same cache key use the same cache, including in different pipelines.
 
-`needs:project` must be used with `job:`, `ref:`, and `artifacts:`.
+If not set, the default key is `default`. All jobs with the `cache:` keyword but
+no `cache:key` share the `default` cache.
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
 **Possible inputs**:
 
-- `needs:project`: A full project path, including namespace and group. If the
-  project is in the same group or namespace, you can omit them from the `project:`
-  keyword. For example: `project: group/project-name` or `project: project-name`.
-- `job`: The job to download artifacts from.
-- `ref`: The ref to download artifacts from.
-- `artifacts`: Must be `true` to download artifacts.
-
-**Examples of `needs:project`**:
-
-```yaml
-build_job:
-  stage: build
-  script:
-    - ls -lhR
-  needs:
-    - project: namespace/group/project-name
-      job: build-1
-      ref: main
-      artifacts: true
-```
-
-In this example, `build_job` downloads the artifacts from the latest successful `build-1` job
-on the `main` branch in the `group/project-name` project.
+- A string.
+- A [predefined variables](../variables/index.md).
+- A combination of both.
 
-In GitLab 13.3 and later, you can use [CI/CD variables](../variables/index.md) in `needs:project`,
-for example:
+**Example of `cache:key`**:
 
 ```yaml
-build_job:
-  stage: build
+cache-job:
   script:
-    - ls -lhR
-  needs:
-    - project: $CI_PROJECT_PATH
-      job: $DEPENDENCY_JOB_NAME
-      ref: $ARTIFACTS_DOWNLOAD_REF
-      artifacts: true
+    - echo "This job uses a cache."
+  cache:
+    key: binaries-cache-$CI_COMMIT_REF_SLUG
+    paths:
+      - binaries/
 ```
 
 **Additional details**:
 
-- To download artifacts from a different pipeline in the current project, set `project:`
-  to be the same as the current project, but use a different ref than the current pipeline.
-  Concurrent pipelines running on the same ref could override the artifacts.
-- The user running the pipeline must have at least the Reporter role for the group or project,
-  or the group/project must have public visibility.
-- You can't use `needs:project` in the same job as [`trigger`](#trigger).
-- When using `needs:project` to download artifacts from another pipeline, the job does not wait for
-  the needed job to complete. [Directed acyclic graph](../directed_acyclic_graph/index.md)
-  behavior is limited to jobs in the same pipeline. Make sure that the needed job in the other
-  pipeline completes before the job that needs it tries to download the artifacts.
-- You can't download artifacts from jobs that run in [`parallel:`](#parallel).
-- Support for [CI/CD variables](../variables/index.md) in `project`, `job`, and `ref` was
-  [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202093) in GitLab 13.3.
-  [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235761) in GitLab 13.4.
-
-**Related topics**:
-
-- To download artifacts between [parent-child pipelines](../pipelines/parent_child_pipelines.md),
-  use [`needs:pipeline:job`](#needspipelinejob).
-
-#### `needs:pipeline:job`
+- If you use **Windows Batch** to run your shell scripts you must replace
+  `$` with `%`. For example: `key: %CI_COMMIT_REF_SLUG%`
+- The `cache:key` value can't contain:
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab 13.7.
+  - The `/` character, or the equivalent URI-encoded `%2F`.
+  - Only the `.` character (any number), or the equivalent URI-encoded `%2E`.
 
-A [child pipeline](../pipelines/parent_child_pipelines.md) can download artifacts from a job in
-its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy.
+- The cache is shared between jobs, so if you're using different
+  paths for different jobs, you should also set a different `cache:key`.
+  Otherwise cache content can be overwritten.
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+**Related topics**:
 
-**Possible inputs**:
+- You can specify a [fallback cache key](../caching/index.md#use-a-fallback-cache-key)
+  to use if the specified `cache:key` is not found.
+- You can [use multiple cache keys](../caching/index.md#use-multiple-caches) in a single job.
+- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more
+  `cache:key` examples.
 
-- `needs:pipeline`: A pipeline ID. Must be a pipeline present in the same parent-child pipeline hierarchy.
-- `job:`: The job to download artifacts from.
+##### `cache:key:files`
 
-**Example of `needs:pipeline:job`**:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5.
 
-- Parent pipeline (`.gitlab-ci.yml`):
+Use the `cache:key:files` keyword to generate a new key when one or two specific files
+change. `cache:key:files` lets you reuse some caches, and rebuild them less often,
+which speeds up subsequent pipeline runs.
 
-  ```yaml
-  create-artifact:
-    stage: build
-    script: echo 'sample artifact' > artifact.txt
-    artifacts:
-      paths: [artifact.txt]
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-  child-pipeline:
-    stage: test
-    trigger:
-      include: child.yml
-      strategy: depend
-    variables:
-      PARENT_PIPELINE_ID: $CI_PIPELINE_ID
-  ```
+**Possible inputs**: An array of one or two file paths.
 
-- Child pipeline (`child.yml`):
+**Example of `cache:key:files`**:
 
-  ```yaml
-  use-artifact:
-    script: cat artifact.txt
-    needs:
-      - pipeline: $PARENT_PIPELINE_ID
-        job: create-artifact
-  ```
+```yaml
+cache-job:
+  script:
+    - echo "This job uses a cache."
+  cache:
+    key:
+      files:
+        - Gemfile.lock
+        - package.json
+    paths:
+      - vendor/ruby
+      - node_modules
+```
 
-In this example, the `create-artifact` job in the parent pipeline creates some artifacts.
-The `child-pipeline` job triggers a child pipeline, and passes the `CI_PIPELINE_ID`
-variable to the child pipeline as a new `PARENT_PIPELINE_ID` variable. The child pipeline
-can use that variable in `needs:pipeline` to download artifacts from the parent pipeline.
+This example creates a cache for Ruby and Node.js dependencies. The cache
+is tied to the current versions of the `Gemfile.lock` and `package.json` files. When one of
+these files changes, a new cache key is computed and a new cache is created. Any future
+job runs that use the same `Gemfile.lock` and `package.json` with `cache:key:files`
+use the new cache, instead of rebuilding the dependencies.
 
 **Additional details**:
 
-- The `pipeline` attribute does not accept the current pipeline ID (`$CI_PIPELINE_ID`).
-  To download artifacts from a job in the current pipeline, use [`needs`](#needsartifacts).
-
-#### `needs:optional`
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30680) in GitLab 13.10.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323891) in GitLab 14.0.
+- The cache `key` is a SHA computed from the most recent commits
+that changed each listed file.
+  If neither file is changed in any commits, the fallback key is `default`.
 
-To need a job that sometimes does not exist in the pipeline, add `optional: true`
-to the `needs` configuration. If not defined, `optional: false` is the default.
+##### `cache:key:prefix`
 
-Jobs that use [`rules`](#rules), [`only`, or `except`](#only--except), might
-not always exist in a pipeline. When the pipeline is created, GitLab checks the `needs`
-relationships before starting it. Without `optional: true`, needs relationships that
-point to a job that does not exist stops the pipeline from starting and causes a pipeline
-error similar to:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5.
 
-- `'job1' job needs 'job2' job, but it was not added to the pipeline`
+Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles).
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
 **Possible inputs**:
 
-- `job:`: The job to make optional.
-- `true` or `false` (default).
+- A string
+- A [predefined variables](../variables/index.md)
+- A combination of both.
 
-**Example of `needs:optional`**:
+**Example of `cache:key:prefix`**:
 
 ```yaml
-build:
-  stage: build
-  rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-
 rspec:
-  stage: test
-  needs:
-    - job: build
-      optional: true
+  script:
+    - echo "This rspec job uses a cache."
+  cache:
+    key:
+      files:
+        - Gemfile.lock
+      prefix: $CI_JOB_NAME
+    paths:
+      - vendor/ruby
 ```
 
-In this example:
+For example, adding a `prefix` of `$CI_JOB_NAME` causes the key to look like `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`.
+If a branch changes `Gemfile.lock`, that branch has a new SHA checksum for `cache:key:files`.
+A new cache key is generated, and a new cache is created for that key. If `Gemfile.lock`
+is not found, the prefix is added to `default`, so the key in the example would be `rspec-default`.
 
-- When the branch is the default branch, the `build` job exists in the pipeline, and the `rspec`
-  job waits for it to complete before starting.
-- When the branch is not the default branch, the `build` job does not exist in the pipeline.
-  The `rspec` job runs immediately (similar to `needs: []`) because its `needs`
-  relationship to the `build` job is optional.
+**Additional details**:
 
-#### `needs:pipeline`
+- If no file in `cache:key:files` is changed in any commits, the prefix is added to the `default` key.
 
-You can mirror the pipeline status from an upstream pipeline to a bridge job by
-using the `needs:pipeline` keyword. The latest pipeline status from the default branch is
-replicated to the bridge job.
+#### `cache:untracked`
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+Use `untracked: true` to cache all files that are untracked in your Git repository:
 
-**Possible inputs**:
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-- A full project path, including namespace and group. If the
-  project is in the same group or namespace, you can omit them from the `project:`
-  keyword. For example: `project: group/project-name` or `project: project-name`.
+**Possible inputs**: `true` or `false` (default).
 
-**Example of `needs:pipeline`**:
+**Example of `cache:untracked`**:
 
 ```yaml
-upstream_bridge:
-  stage: test
-  needs:
-    pipeline: other/project
+rspec:
+  script: test
+  cache:
+    untracked: true
 ```
 
 **Additional details**:
 
-- If you add the `job` keyword to `needs:pipeline`, the job no longer mirrors the
-  pipeline status. The behavior changes to [`needs:pipeline:job`](#needspipelinejob).
+- You can combine `cache:untracked` with `cache:paths` to cache all untracked files
+  as well as files in the configured paths. For example:
 
-### `tags`
+  ```yaml
+  rspec:
+    script: test
+    cache:
+      untracked: true
+      paths:
+        - binaries/
+  ```
 
-> - A limit of 50 tags per job [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338929) in GitLab 14.3.
-> - A limit of 50 tags per job [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/339855) in GitLab 14.3.
+#### `cache:when`
 
-Use `tags` to select a specific runner from the list of all runners that are
-available for the project.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18969) in GitLab 13.5 and GitLab Runner v13.5.0.
 
-When you register a runner, you can specify the runner's tags, for
-example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner must
-be assigned every tag listed in the job.
+Use `cache:when` to define when to save the cache, based on the status of the job.
 
 **Keyword type**: Job keyword. You can use it only as part of a job or in the
 [`default:` section](#default).
 
 **Possible inputs**:
 
-- An array of tag names.
-- [CI/CD variables](../runners/configure_runners.md#use-cicd-variables-in-tags) in GitLab 14.1 and later.
+- `on_success` (default): Save the cache only when the job succeeds.
+- `on_failure`: Save the cache only when the job fails.
+- `always`: Always save the cache.
 
-**Example of `tags`**:
+**Example of `cache:when`**:
 
 ```yaml
-job:
-  tags:
-    - ruby
-    - postgres
+rspec:
+  script: rspec
+  cache:
+    paths:
+      - rspec/
+    when: 'always'
 ```
 
-In this example, only runners with *both* the `ruby` and `postgres` tags can run the job.
+This example stores the cache whether or not the job fails or succeeds.
 
-**Additional details**:
+#### `cache:policy`
 
-- In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later,
-  the number of tags must be less than `50`.
+To change the upload and download behavior of a cache, use the `cache:policy` keyword.
+By default, the job downloads the cache when the job starts, and uploads changes
+to the cache when the job ends. This caching style is the `pull-push` policy (default).
 
-**Related topics**:
+To set a job to only download the cache when the job starts, but never upload changes
+when the job finishes, use `cache:policy:pull`.
 
-- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run).
+To set a job to only upload a cache when the job finishes, but never download the
+cache when the job starts, use `cache:policy:push`.
 
-### `allow_failure`
+Use the `pull` policy when you have many jobs executing in parallel that use the same cache.
+This policy speeds up job execution and reduces load on the cache server. You can
+use a job with the `push` policy to build the cache.
 
-Use `allow_failure` to determine whether a pipeline should continue running when a job fails.
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-- To let the pipeline continue running subsequent jobs, use `allow_failure: true`.
-- To stop the pipeline from running subsequent jobs, use `allow_failure: false`.
+**Possible inputs**:
 
-When jobs are allowed to fail (`allow_failure: true`) an orange warning (**{status_warning}**)
-indicates that a job failed. However, the pipeline is successful and the associated commit
-is marked as passed with no warnings.
+- `pull`
+- `push`
+- `pull-push` (default)
 
-This same warning is displayed when:
+**Example of `cache:policy`**:
 
-- All other jobs in the stage are successful.
-- All other jobs in the pipeline are successful.
+```yaml
+prepare-dependencies-job:
+  stage: build
+  cache:
+    key: gems
+    paths:
+      - vendor/bundle
+    policy: push
+  script:
+    - echo "This job only downloads dependencies and builds the cache."
+    - echo "Downloading dependencies..."
 
-The default value for `allow_failure` is:
+faster-test-job:
+  stage: test
+  cache:
+    key: gems
+    paths:
+      - vendor/bundle
+    policy: pull
+  script:
+    - echo "This job script uses the cache, but does not update it."
+    - echo "Running tests..."
+```
 
-- `true` for [manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually).
-- `false` for manual jobs that also use [`rules`](#rules).
-- `false` in all other cases.
+### `coverage`
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+Use `coverage` with a custom regular expression to configure how code coverage
+is extracted from the job output. The coverage is shown in the UI if at least one
+line in the job output matches the regular expression.
 
-**Possible inputs**: `true` or `false`.
+To extract the code coverage value in the matching line, GitLab uses this
+regular expression: `\d+(\.\d+)?`.
 
-**Example of `allow_failure`**:
+**Possible inputs**: A regular expression. Must start and end with `/`.
+
+**Example of `coverage`**:
 
 ```yaml
 job1:
-  stage: test
-  script:
-    - execute_script_1
-
-job2:
-  stage: test
-  script:
-    - execute_script_2
-  allow_failure: true
-
-job3:
-  stage: deploy
-  script:
-    - deploy_to_staging
+  script: rspec
+  coverage: '/Code coverage: \d+\.\d+/'
 ```
 
-In this example, `job1` and `job2` run in parallel:
+In this example:
 
-- If `job1` fails, jobs in the `deploy` stage do not start.
-- If `job2` fails, jobs in the `deploy` stage can still start.
+1. GitLab checks the job log for a line that matches the regular expression. A line
+   like `Code coverage: 67.89` would match.
+1. GitLab then checks the line to find a match to `\d+(\.\d+)?`. The sample matching
+   line above gives a code coverage of `67.89`.
 
 **Additional details**:
 
-- You can use `allow_failure` as a subkey of [`rules:`](#rulesallow_failure).
-- You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs).
-  A blocked pipeline does not run any jobs in later stages until the manual job
-  is started and completes successfully.
+- If there is more than one matched line in the job output, the last line is used.
+- Leading zeros are removed.
+- Coverage output from [child pipelines](../pipelines/parent_child_pipelines.md)
+  is not recorded or displayed. Check [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/280818)
+  for more details.
 
-#### `allow_failure:exit_codes`
+### `dast_configuration` **(ULTIMATE)**
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) in GitLab 13.8.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) in GitLab 13.9.
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5981) in GitLab 14.1.
 
-Use `allow_failure:exit_codes` to control when a job should be
-allowed to fail. The job is `allow_failure: true` for any of the listed exit codes,
-and `allow_failure` false for any other exit code.
+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 it only as part of a job.
+**Keyword type**: Job keyword. You can use only as part of a job.
 
-**Possible inputs**:
+**Possible inputs**: One each of `site_profile` and `scanner_profile`.
 
-- A single exit code.
-- An array of exit codes.
+- 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 `allow_failure`**:
+**Example of `dast_configuration`**:
 
 ```yaml
-test_job_1:
-  script:
-    - echo "Run a script that results in exit code 1. This job fails."
-    - exit 1
-  allow_failure:
-    exit_codes: 137
+stages:
+  - build
+  - dast
 
-test_job_2:
-  script:
-    - echo "Run a script that results in exit code 137. This job is allowed to fail."
-    - exit 137
-  allow_failure:
-    exit_codes:
-      - 137
-      - 255
+include:
+  - template: DAST.gitlab-ci.yml
+
+dast:
+  dast_configuration:
+    site_profile: "Example Co"
+    scanner_profile: "Quick Passive Test"
 ```
 
-### `when`
+In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword
+to select a specific site profile and scanner profile.
 
-Use `when` to configure the conditions for when jobs run. If not defined in a job,
-the default value is `when: on_success`.
+**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).
+
+### `dependencies`
+
+Use the `dependencies` keyword to define a list of jobs to fetch [artifacts](#artifacts) from.
+You can also set a job to download no artifacts at all.
+
+If you do not use `dependencies`, all artifacts from previous stages are passed to each job.
 
 **Keyword type**: Job keyword. You can use it only as part of a job.
 
 **Possible inputs**:
 
-- `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.
+- The names of jobs to fetch artifacts from.
+- An empty array (`[]`), to configure the job to not download any artifacts.
 
-**Example of `when`**:
+**Example of `dependencies`**:
 
 ```yaml
-stages:
-  - build
-  - cleanup_build
-  - test
-  - deploy
-  - cleanup
+build osx:
+  stage: build
+  script: make build:osx
+  artifacts:
+    paths:
+      - binaries/
 
-build_job:
+build linux:
   stage: build
-  script:
-    - make build
+  script: make build:linux
+  artifacts:
+    paths:
+      - binaries/
 
-cleanup_build_job:
-  stage: cleanup_build
-  script:
-    - cleanup build when failed
-  when: on_failure
+test osx:
+  stage: test
+  script: make test:osx
+  dependencies:
+    - build:osx
 
-test_job:
+test linux:
   stage: test
-  script:
-    - make test
+  script: make test:linux
+  dependencies:
+    - build:linux
 
-deploy_job:
+deploy:
   stage: deploy
-  script:
-    - make deploy
-  when: manual
-
-cleanup_job:
-  stage: cleanup
-  script:
-    - cleanup after jobs
-  when: always
+  script: make deploy
 ```
 
-In this example, the script:
+In this example, two jobs have artifacts: `build osx` and `build linux`. When `test osx` is executed,
+the artifacts from `build osx` are downloaded and extracted in the context of the build.
+The same thing happens for `test linux` and artifacts from `build linux`.
 
-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 `deploy` job downloads artifacts from all previous jobs because of
+the [stage](#stages) precedence.
 
 **Additional details**:
 
-- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), 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`.
-
-**Related topics**:
-
-- `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.
+- The job status does not matter. If a job fails or it's a manual job that isn't triggered, no error occurs.
+- If the artifacts of a dependent job are [expired](#artifactsexpire_in) or
+  [deleted](../pipelines/job_artifacts.md#delete-job-artifacts), then the job fails.
 
 ### `environment`
 
@@ -1999,23 +1590,19 @@ environment.
 
 Use the `action` keyword to specify jobs that prepare, start, or stop environments.
 
-| **Value** | **Description**                                                                                                                                               |
-|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `start`     | Default value. Indicates that job starts the environment. The deployment is created after the job starts.                                                          |
-| `prepare`   | Indicates that the job is only preparing the environment. It does not trigger deployments. [Read more about preparing environments](../environments/index.md#prepare-an-environment-without-creating-a-deployment). |
-| `stop`      | Indicates that job stops deployment. See the example below.                                                                                                   |
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: One of the following keywords:
 
-Take for instance:
+| **Value** | **Description** |
+|:----------|:----------------|
+| `start`   | Default value. Indicates that the job starts the environment. The deployment is created after the job starts. |
+| `prepare` | Indicates that the job is only preparing the environment. It does not trigger deployments. [Read more about preparing environments](../environments/index.md#prepare-an-environment-without-creating-a-deployment). |
+| `stop`    | Indicates that the job stops a deployment. For more detail, read [Stop an environment](../environments/index.md#stop-an-environment). |
 
-```yaml
-review_app:
-  stage: deploy
-  script: make deploy-app
-  environment:
-    name: review/$CI_COMMIT_REF_SLUG
-    url: https://$CI_ENVIRONMENT_SLUG.example.com
-    on_stop: stop_review_app
+**Example of `environment:action`**:
 
+```yaml
 stop_review_app:
   stage: deploy
   variables:
@@ -2027,39 +1614,6 @@ stop_review_app:
     action: stop
 ```
 
-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](../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#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
-on global variables, use [anchor variables](yaml_optimization.md#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`
-to change the job without overriding the global variables.
-
-The `stop_review_app` job is **required** to have the following keywords defined:
-
-- `when`, defined at either:
-  - [The job level](#when).
-  - [In a rules clause](#rules). If you use `rules:` and `when: manual`, you should
-    also set [`allow_failure: true`](#allow_failure) so the pipeline can complete
-    even if the job doesn't run.
-- `environment:name`
-- `environment:action`
-
-Additionally, both jobs should have matching [`rules`](#only--except)
-or [`only/except`](#only--except) configuration.
-
-In the examples above, if the configuration is not identical:
-
-- The `stop_review_app` job might not be included in all pipelines that include the `review_app` job.
-- It is not possible to trigger the `action: stop` to stop the environment automatically.
-
 #### `environment:auto_stop_in`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
@@ -2185,951 +1739,863 @@ The common use case is to create dynamic environments for branches and use them
 as Review Apps. You can see an example that uses Review Apps at
 <https://gitlab.com/gitlab-examples/review-apps-nginx/>.
 
-### `cache`
+### `extends`
 
-Use `cache` to specify a list of files and directories to
-cache between jobs. You can only use paths that are in the local working copy.
+Use `extends` to reuse configuration sections. It's an alternative to [YAML anchors](yaml_optimization.md#anchors)
+and is a little more flexible and readable.
 
-Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts).
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-Learn more about caches in [Caching in GitLab CI/CD](../caching/index.md).
+**Possible inputs:**
 
-#### `cache:paths`
+- The name of another job in the pipeline.
+- A list (array) of names of other jobs in the pipeline.
 
-Use the `cache:paths` keyword to choose which files or directories to cache.
+**Example of `extends`:**
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+```yaml
+.tests:
+  script: rake test
+  stage: test
+  only:
+    refs:
+      - branches
 
-**Possible inputs**: An array of paths relative to the project directory (`$CI_PROJECT_DIR`).
-You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
-patterns:
+rspec:
+  extends: .tests
+  script: rake rspec
+  only:
+    variables:
+      - $RSPEC
+```
 
-- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620),
-[`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match).
-- In GitLab Runner 12.10 and earlier,
-[`filepath.Match`](https://pkg.go.dev/path/filepath#Match).
+In this example, the `rspec` job uses the configuration from the `.tests` template job.
+When creating the pipeline, GitLab:
 
-**Example of `cache:paths`**:
+- Performs a reverse deep merge based on the keys.
+- Merges the `.tests` content with the `rspec` job.
+- Doesn't merge the values of the keys.
 
-Cache all files in `binaries` that end in `.apk` and the `.config` file:
+The result is this `rspec` job:
 
 ```yaml
 rspec:
-  script:
-    - echo "This job uses a cache."
-  cache:
-    key: binaries-cache
-    paths:
-      - binaries/*.apk
-      - .config
+  script: rake rspec
+  stage: test
+  only:
+    refs:
+      - branches
+    variables:
+      - $RSPEC
 ```
 
-**Related topics**:
+**Additional details:**
 
-- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more
-  `cache:paths` examples.
+- In GitLab 12.0 and later, you can use multiple parents for `extends`.
+- The `extends` keyword supports up to eleven levels of inheritance, but you should
+  avoid using more than three levels.
+- In the example above, `.tests` is a [hidden job](../jobs/index.md#hide-jobs),
+  but you can extend configuration from regular jobs as well.
 
-#### `cache:key`
+**Related topics:**
 
-Use the `cache:key` keyword to give each cache a unique identifying key. All jobs
-that use the same cache key use the same cache, including in different pipelines.
+- [Reuse configuration sections by using `extends`](yaml_optimization.md#use-extends-to-reuse-configuration-sections).
+- Use `extends` to reuse configuration from [included configuration files](yaml_optimization.md#use-extends-and-include-together).
 
-If not set, the default key is `default`. All jobs with the `cache:` keyword but
-no `cache:key` share the `default` cache.
+### `image`
+
+Use `image` to specify a Docker image that the job runs in.
 
 **Keyword type**: Job keyword. You can use it only as part of a job or in the
 [`default:` section](#default).
 
-**Possible inputs**:
+**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats:
 
-- A string.
-- A [predefined variables](../variables/index.md).
-- A combination of both.
+- `<image-name>` (Same as using `<image-name>` with the `latest` tag)
+- `<image-name>:<tag>`
+- `<image-name>@<digest>`
 
-**Example of `cache:key`**:
+**Example of `image`**:
 
 ```yaml
-cache-job:
-  script:
-    - echo "This job uses a cache."
-  cache:
-    key: binaries-cache-$CI_COMMIT_REF_SLUG
-    paths:
-      - binaries/
-```
-
-**Additional details**:
+default:
+  image: ruby:3.0
 
-- If you use **Windows Batch** to run your shell scripts you must replace
-  `$` with `%`. For example: `key: %CI_COMMIT_REF_SLUG%`
-- The `cache:key` value can't contain:
+rspec:
+  script: bundle exec rspec
 
-  - The `/` character, or the equivalent URI-encoded `%2F`.
-  - Only the `.` character (any number), or the equivalent URI-encoded `%2E`.
+rspec 2.7:
+  image: registry.example.com/my-group/my-project/ruby:2.7
+  script: bundle exec rspec
+```
 
-- The cache is shared between jobs, so if you're using different
-  paths for different jobs, you should also set a different `cache:key`.
-  Otherwise cache content can be overwritten.
+In this example, the `ruby:3.0` image is the default for all jobs in the pipeline.
+The `rspec 2.7` job does not use the default, because it overrides the default with
+a job-specific `image:` section.
 
 **Related topics**:
 
-- You can specify a [fallback cache key](../caching/index.md#use-a-fallback-cache-key)
-  to use if the specified `cache:key` is not found.
-- You can [use multiple cache keys](../caching/index.md#use-multiple-caches) in a single job.
-- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more
-  `cache:key` examples.
-
-##### `cache:key:files`
+- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md).
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5.
+#### `image:name`
 
-Use the `cache:key:files` keyword to generate a new key when one or two specific files
-change. `cache:key:files` lets you reuse some caches, and rebuild them less often,
-which speeds up subsequent pipeline runs.
+The name of the Docker image that the job runs in. Similar to [`image:`](#image) used by itself.
 
 **Keyword type**: Job keyword. You can use it only as part of a job or in the
 [`default:` section](#default).
 
-**Possible inputs**: An array of one or two file paths.
+**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats:
 
-**Example of `cache:key:files`**:
+- `<image-name>` (Same as using `<image-name>` with the `latest` tag)
+- `<image-name>:<tag>`
+- `<image-name>@<digest>`
+
+**Example of `image:name`**:
 
 ```yaml
-cache-job:
-  script:
-    - echo "This job uses a cache."
-  cache:
-    key:
-      files:
-        - Gemfile.lock
-        - package.json
-    paths:
-      - vendor/ruby
-      - node_modules
+image:
+  name: "registry.example.com/my/image:latest"
 ```
 
-This example creates a cache for Ruby and Node.js dependencies. The cache
-is tied to the current versions of the `Gemfile.lock` and `package.json` files. When one of
-these files changes, a new cache key is computed and a new cache is created. Any future
-job runs that use the same `Gemfile.lock` and `package.json` with `cache:key:files`
-use the new cache, instead of rebuilding the dependencies.
-
-**Additional details**:
+**Related topics**:
 
-- The cache `key` is a SHA computed from the most recent commits
-that changed each listed file.
-  If neither file is changed in any commits, the fallback key is `default`.
+- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md).
 
-##### `cache:key:prefix`
+#### `image:entrypoint`
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5.
+Command or script to execute as the container's entry point.
 
-Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles).
+When the Docker container is created, the `entrypoint` is translated to the Docker `--entrypoint` option.
+The syntax is similar to the [Dockerfile `ENTRYPOINT` directive](https://docs.docker.com/engine/reference/builder/#entrypoint),
+where each shell token is a separate string in the array.
 
 **Keyword type**: Job keyword. You can use it only as part of a job or in the
 [`default:` section](#default).
 
-**Possible inputs**:
-
-- A string
-- A [predefined variables](../variables/index.md)
-- A combination of both.
+**Possible inputs**: A string.
 
-**Example of `cache:key:prefix`**:
+**Example of `image:entrypoint`**:
 
 ```yaml
-rspec:
-  script:
-    - echo "This rspec job uses a cache."
-  cache:
-    key:
-      files:
-        - Gemfile.lock
-      prefix: $CI_JOB_NAME
-    paths:
-      - vendor/ruby
+image:
+  name: super/sql:experimental
+  entrypoint: [""]
 ```
 
-For example, adding a `prefix` of `$CI_JOB_NAME` causes the key to look like `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`.
-If a branch changes `Gemfile.lock`, that branch has a new SHA checksum for `cache:key:files`.
-A new cache key is generated, and a new cache is created for that key. If `Gemfile.lock`
-is not found, the prefix is added to `default`, so the key in the example would be `rspec-default`.
+**Related topics**:
 
-**Additional details**:
+- [Override the entrypoint of an image](../docker/using_docker_images.md#override-the-entrypoint-of-an-image).
 
-- If no file in `cache:key:files` is changed in any commits, the prefix is added to the `default` key.
+### `inherit`
 
-#### `cache:untracked`
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9.
 
-Use `untracked: true` to cache all files that are untracked in your Git repository:
+Use `inherit:` to [control inheritance of globally-defined defaults and variables](../jobs/index.md#control-the-inheritance-of-default-keywords-and-global-variables).
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+#### `inherit:default`
 
-**Possible inputs**: `true` or `false` (default).
+Use `inherit:default` to control the inheritance of [default keywords](#default).
 
-**Example of `cache:untracked`**:
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**:
+
+- `true` (default) or `false` to enable or disable the inheritance of all default keywords.
+- A list of specific default keywords to inherit.
+
+**Example of `inherit:default`:**
 
 ```yaml
-rspec:
-  script: test
-  cache:
-    untracked: true
-```
+default:
+  retry: 2
+  image: ruby:3.0
+  interruptible: true
 
-**Additional details**:
+job1:
+  script: echo "This job does not inherit any default keywords."
+  inherit:
+    default: false
 
-- You can combine `cache:untracked` with `cache:paths` to cache all untracked files
-  as well as files in the configured paths. For example:
+job2:
+  script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'."
+  inherit:
+    default:
+      - retry
+      - image
+```
 
-  ```yaml
-  rspec:
-    script: test
-    cache:
-      untracked: true
-      paths:
-        - binaries/
-  ```
+**Additional details:**
 
-#### `cache:when`
+- You can also list default keywords to inherit on one line: `default: [keyword1, keyword2]`
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18969) in GitLab 13.5 and GitLab Runner v13.5.0.
+#### `inherit:variables`
 
-Use `cache:when` to define when to save the cache, based on the status of the job.
+Use `inherit:variables` to control the inheritance of [global variables](#variables) keywords.
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
 **Possible inputs**:
 
-- `on_success` (default): Save the cache only when the job succeeds.
-- `on_failure`: Save the cache only when the job fails.
-- `always`: Always save the cache.
+- `true` (default) or `false` to enable or disable the inheritance of all global variables.
+- A list of specific variables to inherit.
 
-**Example of `cache:when`**:
+**Example of `inherit:variables`:**
 
 ```yaml
-rspec:
-  script: rspec
-  cache:
-    paths:
-      - rspec/
-    when: 'always'
+variables:
+  VARIABLE1: "This is variable 1"
+  VARIABLE2: "This is variable 2"
+  VARIABLE3: "This is variable 3"
+
+job1:
+  script: echo "This job does not inherit any global variables."
+  inherit:
+    variables: false
+
+job2:
+  script: echo "This job inherits only the two listed global variables. It does not inherit 'VARIABLE3'."
+  inherit:
+    variables:
+      - VARIABLE1
+      - VARIABLE2
 ```
 
-This example stores the cache whether or not the job fails or succeeds.
+**Additional details:**
 
-#### `cache:policy`
+- You can also list global variables to inherit on one line: `variables: [VARIABLE1, VARIABLE2]`
 
-To change the upload and download behavior of a cache, use the `cache:policy` keyword.
-By default, the job downloads the cache when the job starts, and uploads changes
-to the cache when the job ends. This caching style is the `pull-push` policy (default).
+### `interruptible`
 
-To set a job to only download the cache when the job starts, but never upload changes
-when the job finishes, use `cache:policy:pull`.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3.
 
-To set a job to only upload a cache when the job finishes, but never download the
-cache when the job starts, use `cache:policy:push`.
+Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes.
 
-Use the `pull` policy when you have many jobs executing in parallel that use the same cache.
-This policy speeds up job execution and reduces load on the cache server. You can
-use a job with the `push` policy to build the cache.
+This keyword is used with the [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines)
+feature. When enabled, a running job with `interruptible: true` can be cancelled when
+a new pipeline starts on the same branch.
+
+You can't cancel subsequent jobs after a job with `interruptible: false` starts.
 
 **Keyword type**: Job keyword. You can use it only as part of a job or in the
 [`default:` section](#default).
 
-**Possible inputs**:
-
-- `pull`
-- `push`
-- `pull-push` (default)
+**Possible inputs**: `true` or `false` (default).
 
-**Example of `cache:policy`**:
+**Example of `interruptible`**:
 
 ```yaml
-prepare-dependencies-job:
-  stage: build
-  cache:
-    key: gems
-    paths:
-      - vendor/bundle
-    policy: push
+stages:
+  - stage1
+  - stage2
+  - stage3
+
+step-1:
+  stage: stage1
   script:
-    - echo "This job only downloads dependencies and builds the cache."
-    - echo "Downloading dependencies..."
+    - echo "Can be canceled."
+  interruptible: true
 
-faster-test-job:
-  stage: test
-  cache:
-    key: gems
-    paths:
-      - vendor/bundle
-    policy: pull
+step-2:
+  stage: stage2
   script:
-    - echo "This job script uses the cache, but does not update it."
-    - echo "Running tests..."
+    - echo "Can not be canceled."
+
+step-3:
+  stage: stage3
+  script:
+    - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible."
+  interruptible: true
 ```
 
-### `dependencies`
+In this example, a new pipeline causes a running pipeline to be:
 
-Use the `dependencies` keyword to define a list of jobs to fetch [artifacts](#artifacts) from.
-You can also set a job to download no artifacts at all.
+- Canceled, if only `step-1` is running or pending.
+- Not canceled, after `step-2` starts.
 
-If you do not use `dependencies`, all artifacts from previous stages are passed to each job.
+**Additional details**:
+
+- Only set `interruptible: true` if the job can be safely canceled after it has started,
+  like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments.
+- To completely cancel a running pipeline, all jobs must have `interruptible: true`,
+  or `interruptible: false` jobs must not have started.
+
+### `needs`
+
+> - [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).
+
+You can ignore stage ordering and run some jobs without waiting for others to complete.
+Jobs in multiple stages can run concurrently.
 
 **Keyword type**: Job keyword. You can use it only as part of a job.
 
 **Possible inputs**:
 
-- The names of jobs to fetch artifacts from.
-- An empty array (`[]`), to configure the job to not download any artifacts.
+- An array of jobs.
+- An empty array (`[]`), to set the job to start as soon as the pipeline is created.
 
-**Example of `dependencies`**:
+**Example of `needs`**:
 
 ```yaml
-build osx:
+linux:build:
   stage: build
-  script: make build:osx
-  artifacts:
-    paths:
-      - binaries/
+  script: echo "Building linux..."
 
-build linux:
+mac:build:
   stage: build
-  script: make build:linux
-  artifacts:
-    paths:
-      - binaries/
+  script: echo "Building mac..."
 
-test osx:
+lint:
   stage: test
-  script: make test:osx
-  dependencies:
-    - build:osx
+  needs: []
+  script: echo "Linting..."
 
-test linux:
+linux:rspec:
   stage: test
-  script: make test:linux
-  dependencies:
-    - build:linux
+  needs: ["linux:build"]
+  script: echo "Running rspec on linux..."
 
-deploy:
+mac:rspec:
+  stage: test
+  needs: ["mac:build"]
+  script: echo "Running rspec on mac..."
+
+production:
   stage: deploy
-  script: make deploy
+  script: echo "Running production..."
 ```
 
-In this example, two jobs have artifacts: `build osx` and `build linux`. When `test osx` is executed,
-the artifacts from `build osx` are downloaded and extracted in the context of the build.
-The same thing happens for `test linux` and artifacts from `build linux`.
+This example creates four paths of execution:
 
-The `deploy` job downloads artifacts from all previous jobs because of
-the [stage](#stages) precedence.
+- Linter: The `lint` job runs immediately without waiting for the `build` stage
+  to complete because it has no needs (`needs: []`).
+- Linux path: The `linux:rspec` job runs as soon as the `linux:build`
+  job finishes, without waiting for `mac:build` to finish.
+- macOS path: The `mac:rspec` jobs runs as soon as the `mac:build`
+  job finishes, without waiting for `linux:build` to finish.
+- The `production` job runs as soon as all previous jobs finish:
+  `linux:build`, `linux:rspec`, `mac:build`, `mac:rspec`.
 
 **Additional details**:
 
-- The job status does not matter. If a job fails or it's a manual job that isn't triggered, no error occurs.
-- If the artifacts of a dependent job are [expired](#artifactsexpire_in) or
-  [deleted](../pipelines/job_artifacts.md#delete-job-artifacts), then the job fails.
-
-### `artifacts`
-
-Use `artifacts` to specify a list of files and directories that are
-attached to the job when it [succeeds, fails, or always](#artifactswhen).
-
-The artifacts are sent to GitLab after the job finishes. They are
-available for download in the GitLab UI if the size is not
-larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd).
-
-By default, jobs in later stages automatically download all the artifacts created
-by jobs in earlier stages. You can control artifact download behavior in jobs with
-[`dependencies`](#dependencies).
+- The maximum number of jobs that a single job can have in the `needs:` array is limited:
+  - For GitLab.com, the limit is 50. For more information, see our
+    [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541).
+  - For self-managed instances, the default limit is 50. This limit [can be changed](../../administration/cicd.md#set-the-needs-job-limit).
+- If `needs:` refers to a job that uses the [`parallel`](#parallel) keyword,
+  it depends on all jobs created in parallel, not just one job. It also downloads
+  artifacts from all the parallel jobs by default. If the artifacts have the same
+  name, they overwrite each other and only the last one downloaded is saved.
+- 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.
+- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. Stages must be
+  explicitly defined for all jobs that use the `needs:` keyword, or are referenced
+  in a job's `needs:` section.
+- 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.
 
-When using the [`needs`](#needs) keyword, jobs can only download
-artifacts from the jobs defined in the `needs` configuration.
+#### `needs:artifacts`
 
-Job artifacts are only collected for successful jobs by default, and
-artifacts are restored after [caches](#cache).
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.6.
 
-[Read more about artifacts](../pipelines/job_artifacts.md).
+When a job uses `needs`, it no longer downloads all artifacts from previous stages
+by default, because jobs with `needs` can start before earlier stages complete. With
+`needs` you can only download artifacts from the jobs listed in the `needs:` configuration.
 
-#### `artifacts:exclude`
+Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are
+downloaded in jobs that use `needs`.
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) in GitLab 13.1
-> - Requires GitLab Runner 13.1
+**Keyword type**: Job keyword. You can use it only as part of a job. Must be used with `needs:job`.
 
-`exclude` makes it possible to prevent files from being added to an artifacts
-archive.
+**Possible inputs**:
 
-Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative
-to the project directory. You can use Wildcards that use
-[glob](https://en.wikipedia.org/wiki/Glob_(programming)) or
-[`doublestar.PathMatch`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#PathMatch) patterns.
+- `true` (default) or `false`.
 
-For example, to store all files in `binaries/`, but not `*.o` files located in
-subdirectories of `binaries/`:
+**Example of `needs:artifacts`**:
 
 ```yaml
-artifacts:
-  paths:
-    - binaries/
-  exclude:
-    - binaries/**/*.o
-```
-
-Unlike [`artifacts:paths`](#artifactspaths), `exclude` paths are not recursive. To exclude all of the contents of a directory, you can match them explicitly rather than matching the directory itself.
+test-job1:
+  stage: test
+  needs:
+    - job: build_job1
+      artifacts: true
 
-For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory:
+test-job2:
+  stage: test
+  needs:
+    - job: build_job2
+      artifacts: false
 
-```yaml
-artifacts:
-  paths:
-    - binaries/
-  exclude:
-    - binaries/temp/**/*
+test-job3:
+  needs:
+    - job: build_job1
+      artifacts: true
+    - job: build_job2
+    - build_job3
 ```
 
-Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded using
-`artifacts:exclude` too.
-
-#### `artifacts:expire_in`
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0 behind a disabled feature flag, the latest job artifacts are kept regardless of expiry time.
-> - [Made default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8, keeping latest job artifacts can be disabled at the project level.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276583) in GitLab 13.9, keeping latest job artifacts can be disabled instance-wide.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321323) in GitLab 13.12, the latest pipeline artifacts are kept regardless of expiry time.
-
-Use `expire_in` to specify how long [job artifacts](../pipelines/job_artifacts.md) are stored before
-they expire and are deleted. The `expire_in` setting does not affect:
-
-- Artifacts from the latest job, unless keeping the latest job artifacts is:
-  - [Disabled at the project level](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs).
-  - [Disabled instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
-- [Pipeline artifacts](../pipelines/pipeline_artifacts.md). You can't specify an expiration date for
-  pipeline artifacts. See [When pipeline artifacts are deleted](../pipelines/pipeline_artifacts.md#when-pipeline-artifacts-are-deleted)
-  for more information.
+In this example:
 
-The value of `expire_in` is an elapsed time in seconds, unless a unit is provided. Valid values
-include:
+- The `test-job1` job downloads the `build_job1` artifacts
+- The `test-job2` job does not download the `build_job2` artifacts.
+- The `test-job3` job downloads the artifacts from all three `build_jobs`, because
+  `artifacts:` is `true`, or defaults to `true`, for all three needed jobs.
 
-- `'42'`
-- `42 seconds`
-- `3 mins 4 sec`
-- `2 hrs 20 min`
-- `2h20min`
-- `6 mos 1 day`
-- `47 yrs 6 mos and 4d`
-- `3 weeks and 2 days`
-- `never`
+**Additional details**:
 
-To expire artifacts one week after being uploaded:
+- In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword
+  with `needs`.
 
-```yaml
-job:
-  artifacts:
-    expire_in: 1 week
-```
+#### `needs:project` **(PREMIUM)**
 
-The expiration time period begins when the artifact is uploaded and stored on GitLab. If the expiry
-time is not defined, it defaults to the
-[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration)
-(30 days by default).
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.7.
 
-To override the expiration date and protect artifacts from being automatically deleted:
+Use `needs:project` to download artifacts from up to five jobs in other pipelines.
+The artifacts are downloaded from the latest successful pipeline for the specified ref.
 
-- Select **Keep** on the job page.
-- [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of
-  `expire_in` to `never`.
+If there is a pipeline running for the specified ref, a job with `needs:project`
+does not wait for the pipeline to complete. Instead, the job downloads the artifact
+from the latest pipeline that completed successfully.
 
-After their expiry, artifacts are deleted hourly by default (using a cron job), and are not
-accessible anymore.
+`needs:project` must be used with `job:`, `ref:`, and `artifacts:`.
 
-#### `artifacts:expose_as`
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5.
+**Possible inputs**:
 
-Use the `expose_as` keyword to expose [job artifacts](../pipelines/job_artifacts.md)
-in the [merge request](../../user/project/merge_requests/index.md) UI.
+- `needs:project`: A full project path, including namespace and group. If the
+  project is in the same group or namespace, you can omit them from the `project:`
+  keyword. For example: `project: group/project-name` or `project: project-name`.
+- `job`: The job to download artifacts from.
+- `ref`: The ref to download artifacts from.
+- `artifacts`: Must be `true` to download artifacts.
 
-For example, to match a single file:
+**Examples of `needs:project`**:
 
 ```yaml
-test:
-  script: ["echo 'test' > file.txt"]
-  artifacts:
-    expose_as: 'artifact 1'
-    paths: ['file.txt']
+build_job:
+  stage: build
+  script:
+    - ls -lhR
+  needs:
+    - project: namespace/group/project-name
+      job: build-1
+      ref: main
+      artifacts: true
 ```
 
-With this configuration, GitLab adds a link **artifact 1** to the relevant merge request
-that points to `file1.txt`. To access the link, select **View exposed artifact**
-below the pipeline graph in the merge request overview.
+In this example, `build_job` downloads the artifacts from the latest successful `build-1` job
+on the `main` branch in the `group/project-name` project.
 
-An example that matches an entire directory:
+In GitLab 13.3 and later, you can use [CI/CD variables](../variables/index.md) in `needs:project`,
+for example:
 
 ```yaml
-test:
-  script: ["mkdir test && echo 'test' > test/file.txt"]
-  artifacts:
-    expose_as: 'artifact 1'
-    paths: ['test/']
+build_job:
+  stage: build
+  script:
+    - ls -lhR
+  needs:
+    - project: $CI_PROJECT_PATH
+      job: $DEPENDENCY_JOB_NAME
+      ref: $ARTIFACTS_DOWNLOAD_REF
+      artifacts: true
 ```
 
-Note the following:
+**Additional details**:
 
-- Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`.
-- A maximum of 10 job artifacts per merge request can be exposed.
-- Glob patterns are unsupported.
-- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#download-job-artifacts) if there is more than
-  one file in the directory.
-- For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`,
-  and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is:
-  - Enabled, GitLab automatically renders the artifact.
-  - Not enabled, the file is displayed in the artifacts browser.
+- To download artifacts from a different pipeline in the current project, set `project:`
+  to be the same as the current project, but use a different ref than the current pipeline.
+  Concurrent pipelines running on the same ref could override the artifacts.
+- The user running the pipeline must have at least the Reporter role for the group or project,
+  or the group/project must have public visibility.
+- You can't use `needs:project` in the same job as [`trigger`](#trigger).
+- When using `needs:project` to download artifacts from another pipeline, the job does not wait for
+  the needed job to complete. [Directed acyclic graph](../directed_acyclic_graph/index.md)
+  behavior is limited to jobs in the same pipeline. Make sure that the needed job in the other
+  pipeline completes before the job that needs it tries to download the artifacts.
+- You can't download artifacts from jobs that run in [`parallel:`](#parallel).
+- Support for [CI/CD variables](../variables/index.md) in `project`, `job`, and `ref` was
+  [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202093) in GitLab 13.3.
+  [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235761) in GitLab 13.4.
 
-#### `artifacts:name`
+**Related topics**:
 
-Use the `name` directive to define the name of the created artifacts
-archive. You can specify a unique name for every archive. The `artifacts:name`
-variable can make use of any of the [predefined variables](../variables/index.md).
-The default name is `artifacts`, which becomes `artifacts.zip` when you download it.
+- To download artifacts between [parent-child pipelines](../pipelines/parent_child_pipelines.md),
+  use [`needs:pipeline:job`](#needspipelinejob).
 
-To create an archive with a name of the current job:
+#### `needs:pipeline:job`
 
-```yaml
-job:
-  artifacts:
-    name: "$CI_JOB_NAME"
-    paths:
-      - binaries/
-```
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab 13.7.
 
-To create an archive with a name of the current branch or tag including only
-the binaries directory:
+A [child pipeline](../pipelines/parent_child_pipelines.md) can download artifacts from a job in
+its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy.
 
-```yaml
-job:
-  artifacts:
-    name: "$CI_COMMIT_REF_NAME"
-    paths:
-      - binaries/
-```
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-If your branch-name contains forward slashes
-(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG`
-instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact.
+**Possible inputs**:
 
-To create an archive with a name of the current job and the current branch or
-tag including only the binaries directory:
+- `needs:pipeline`: A pipeline ID. Must be a pipeline present in the same parent-child pipeline hierarchy.
+- `job:`: The job to download artifacts from.
 
-```yaml
-job:
-  artifacts:
-    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
-    paths:
-      - binaries/
-```
+**Example of `needs:pipeline:job`**:
 
-To create an archive with a name of the current [stage](#stages) and branch name:
+- Parent pipeline (`.gitlab-ci.yml`):
 
-```yaml
-job:
-  artifacts:
-    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
-    paths:
-      - binaries/
-```
+  ```yaml
+  create-artifact:
+    stage: build
+    script: echo 'sample artifact' > artifact.txt
+    artifacts:
+      paths: [artifact.txt]
 
----
+  child-pipeline:
+    stage: test
+    trigger:
+      include: child.yml
+      strategy: depend
+    variables:
+      PARENT_PIPELINE_ID: $CI_PIPELINE_ID
+  ```
 
-If you use **Windows Batch** to run your shell scripts you must replace
-`$` with `%`:
+- Child pipeline (`child.yml`):
 
-```yaml
-job:
-  artifacts:
-    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
-    paths:
-      - binaries/
-```
+  ```yaml
+  use-artifact:
+    script: cat artifact.txt
+    needs:
+      - pipeline: $PARENT_PIPELINE_ID
+        job: create-artifact
+  ```
 
-If you use **Windows PowerShell** to run your shell scripts you must replace
-`$` with `$env:`:
+In this example, the `create-artifact` job in the parent pipeline creates some artifacts.
+The `child-pipeline` job triggers a child pipeline, and passes the `CI_PIPELINE_ID`
+variable to the child pipeline as a new `PARENT_PIPELINE_ID` variable. The child pipeline
+can use that variable in `needs:pipeline` to download artifacts from the parent pipeline.
 
-```yaml
-job:
-  artifacts:
-    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
-    paths:
-      - binaries/
-```
+**Additional details**:
 
-#### `artifacts:paths`
+- The `pipeline` attribute does not accept the current pipeline ID (`$CI_PIPELINE_ID`).
+  To download artifacts from a job in the current pipeline, use [`needs`](#needsartifacts).
 
-Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly
-link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
-patterns and:
+#### `needs:optional`
 
-- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620),
-  [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match).
-- In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match).
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30680) in GitLab 13.10.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323891) in GitLab 14.0.
 
-To restrict which jobs a specific job fetches artifacts from, see [dependencies](#dependencies).
+To need a job that sometimes does not exist in the pipeline, add `optional: true`
+to the `needs` configuration. If not defined, `optional: false` is the default.
 
-Send all files in `binaries` and `.config`:
+Jobs that use [`rules`](#rules), [`only`, or `except`](#only--except), might
+not always exist in a pipeline. When the pipeline is created, GitLab checks the `needs`
+relationships before starting it. Without `optional: true`, needs relationships that
+point to a job that does not exist stops the pipeline from starting and causes a pipeline
+error similar to:
 
-```yaml
-artifacts:
-  paths:
-    - binaries/
-    - .config
-```
+- `'job1' job needs 'job2' job, but it was not added to the pipeline`
 
-To disable artifact passing, define the job with empty [dependencies](#dependencies):
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-```yaml
-job:
-  stage: build
-  script: make build
-  dependencies: []
-```
+**Possible inputs**:
 
-You may want to create artifacts only for tagged releases to avoid filling the
-build server storage with temporary build artifacts.
+- `job:`: The job to make optional.
+- `true` or `false` (default).
 
-Create artifacts only for tags (`default-job` doesn't create artifacts):
+**Example of `needs:optional`**:
 
 ```yaml
-default-job:
-  script:
-    - mvn test -U
-  rules:
-    - if: $CI_COMMIT_BRANCH
-
-release-job:
-  script:
-    - mvn package -U
-  artifacts:
-    paths:
-      - target/*.war
+build:
+  stage: build
   rules:
-    - if: $CI_COMMIT_TAG
-```
-
-You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with `xyz`:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 
-```yaml
-job:
-  artifacts:
-    paths:
-      - path/*xyz/*
+rspec:
+  stage: test
+  needs:
+    - job: build
+      optional: true
 ```
 
-#### `artifacts:public`
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49775) in GitLab 13.8
-> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
-> - It's disabled on GitLab.com.
-> - It's recommended for production use.
-
-Use `artifacts:public` to determine whether the job artifacts should be
-publicly available.
-
-The default for `artifacts:public` is `true` which means that the artifacts in
-public pipelines are available for download by anonymous and guest users:
-
-```yaml
-artifacts:
-  public: true
-```
+In this example:
 
-To deny read access for anonymous and guest users to artifacts in public
-pipelines, set `artifacts:public` to `false`:
+- When the branch is the default branch, the `build` job exists in the pipeline, and the `rspec`
+  job waits for it to complete before starting.
+- When the branch is not the default branch, the `build` job does not exist in the pipeline.
+  The `rspec` job runs immediately (similar to `needs: []`) because its `needs`
+  relationship to the `build` job is optional.
 
-```yaml
-artifacts:
-  public: false
-```
+#### `needs:pipeline`
 
-#### `artifacts:reports`
+You can mirror the pipeline status from an upstream pipeline to a bridge job by
+using the `needs:pipeline` keyword. The latest pipeline status from the default branch is
+replicated to the bridge job.
 
-Use [`artifacts:reports`](artifacts_reports.md) to collect artifacts generated by
-included templates in jobs.
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+**Possible inputs**:
 
-**Possible inputs**: See list of available [artifacts reports types](artifacts_reports.md).
+- A full project path, including namespace and group. If the
+  project is in the same group or namespace, you can omit them from the `project:`
+  keyword. For example: `project: group/project-name` or `project: project-name`.
 
-**Example of `artifacts:reports`**:
+**Example of `needs:pipeline`**:
 
 ```yaml
-rspec:
+upstream_bridge:
   stage: test
-  script:
-    - bundle install
-    - rspec --format RspecJunitFormatter --out rspec.xml
-  artifacts:
-    reports:
-      junit: rspec.xml
+  needs:
+    pipeline: other/project
 ```
 
 **Additional details**:
 
-- Combining reports in parent pipelines using [artifacts from child pipelines](#needspipelinejob) is
-  not supported. Track progress on adding support in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215725).
-- To be able to browse the report output files, include the [`artifacts:paths`](#artifactspaths) keyword.
-- The test reports are collected regardless of the job results (success or failure).
-  You can use [`artifacts:expire_in`](#artifactsexpire_in) to set up an expiration
-  date for artifacts reports.
-
-#### `artifacts:untracked`
-
-Use `artifacts:untracked` to add all Git untracked files as artifacts (along
-with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration
-in the repository's `.gitignore` file.
-
-Send all Git untracked files:
-
-```yaml
-artifacts:
-  untracked: true
-```
-
-Send all Git untracked files and files in `binaries`:
+- If you add the `job` keyword to `needs:pipeline`, the job no longer mirrors the
+  pipeline status. The behavior changes to [`needs:pipeline:job`](#needspipelinejob).
 
-```yaml
-artifacts:
-  untracked: true
-  paths:
-    - binaries/
-```
+### `only` / `except`
 
-Send all untracked files but [exclude](#artifactsexclude) `*.txt`:
+NOTE:
+`only` and `except` are not being actively developed. [`rules`](#rules) is the preferred
+keyword to control when to add jobs to pipelines.
 
-```yaml
-artifacts:
-  untracked: true
-  exclude:
-    - "*.txt"
-```
+You can use `only` and `except` to control when to add jobs to pipelines.
 
-#### `artifacts:when`
+- Use `only` to define when a job runs.
+- Use `except` to define when a job **does not** run.
 
-Use `artifacts:when` to upload artifacts on job failure or despite the
-failure.
+Four keywords can be used with `only` and `except`:
 
-`artifacts:when` can be set to one of the following values:
+- [`refs`](#onlyrefs--exceptrefs)
+- [`variables`](#onlyvariables--exceptvariables)
+- [`changes`](#onlychanges--exceptchanges)
+- [`kubernetes`](#onlykubernetes--exceptkubernetes)
 
-1. `on_success` (default): Upload artifacts only when the job succeeds.
-1. `on_failure`: Upload artifacts only when the job fails.
-1. `always`: Always upload artifacts. For example, when
-   [uploading artifacts](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab) required to
-   troubleshoot failing tests.
+See [specify when jobs run with `only` and `except`](../jobs/job_control.md#specify-when-jobs-run-with-only-and-except)
+for more details and examples.
 
-For example, to upload artifacts only when a job fails:
+#### `only:refs` / `except:refs`
 
-```yaml
-job:
-  artifacts:
-    when: on_failure
-```
+Use the `only:refs` and `except:refs` keywords to control when to add jobs to a
+pipeline based on branch names or pipeline types.
 
-### `coverage`
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-Use `coverage` with a custom regular expression to configure how code coverage
-is extracted from the job output. The coverage is shown in the UI if at least one
-line in the job output matches the regular expression.
+**Possible inputs**: An array including any number of:
 
-To extract the code coverage value in the matching line, GitLab uses this
-regular expression: `\d+(\.\d+)?`.
+- Branch names, for example `main` or `my-feature-branch`.
+- [Regular expressions](../jobs/job_control.md#only--except-regex-syntax)
+  that match against branch names, for example `/^feature-.*/`.
+- The following keywords:
 
-**Possible inputs**: A regular expression. Must start and end with `/`.
+  | **Value**                | **Description** |
+  | -------------------------|-----------------|
+  | `api`                    | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). |
+  | `branches`               | When the Git reference for a pipeline is a branch. |
+  | `chat`                   | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. |
+  | `external`               | When you use CI services other than GitLab. |
+  | `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). |
+  | `merge_requests`         | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../pipelines/merge_request_pipelines.md), [merged results pipelines](../pipelines/pipelines_for_merged_results.md), and [merge trains](../pipelines/merge_trains.md). |
+  | `pipelines`              | For [multi-project pipelines](../pipelines/multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../pipelines/multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](#trigger) keyword. |
+  | `pushes`                 | For pipelines triggered by a `git push` event, including for branches and tags. |
+  | `schedules`              | For [scheduled pipelines](../pipelines/schedules.md). |
+  | `tags`                   | When the Git reference for a pipeline is a tag. |
+  | `triggers`               | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). |
+  | `web`                    | For pipelines created by selecting **Run pipeline** in the GitLab UI, from the project's **CI/CD > Pipelines** section. |
 
-**Example of `coverage`**:
+**Example of `only:refs` and `except:refs`**:
 
 ```yaml
 job1:
-  script: rspec
-  coverage: '/Code coverage: \d+\.\d+/'
+  script: echo
+  only:
+    - main
+    - /^issue-.*$/
+    - merge_requests
+
+job2:
+  script: echo
+  except:
+    - main
+    - /^stable-branch.*$/
+    - schedules
 ```
 
-In this example:
+**Additional details:**
 
-1. GitLab checks the job log for a line that matches the regular expression. A line
-   like `Code coverage: 67.89` would match.
-1. GitLab then checks the line to find a match to `\d+(\.\d+)?`. The sample matching
-   line above gives a code coverage of `67.89`.
+- Scheduled pipelines run on specific branches, so jobs configured with `only: branches`
+  run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches`
+  from running on scheduled pipelines.
+- `only` or `except` used without any other keywords are equivalent to `only: refs`
+  or `except: refs`. For example, the following two jobs configurations have the same
+  behavior:
 
-**Additional details**:
+  ```yaml
+  job1:
+    script: echo
+    only:
+      - branches
 
-- If there is more than one matched line in the job output, the last line is used.
-- Leading zeros are removed.
-- Coverage output from [child pipelines](../pipelines/parent_child_pipelines.md)
-  is not recorded or displayed. Check [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/280818)
-  for more details.
+  job2:
+    script: echo
+    only:
+      refs:
+        - branches
+  ```
 
-### `dast_configuration` **(ULTIMATE)**
+- If a job does not use `only`, `except`, or [`rules`](#rules), then `only` is set to `branches`
+  and `tags` by default.
 
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5981) in GitLab 14.1.
+  For example, `job1` and `job2` are equivalent:
 
-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`.
+  ```yaml
+  job1:
+    script: echo 'test'
 
-**Keyword type**: Job keyword. You can use only as part of a job.
+  job2:
+    script: echo 'test'
+    only:
+    - branches
+    - tags
+  ```
 
-**Possible inputs**: One each of `site_profile` and `scanner_profile`.
+#### `only:variables` / `except:variables`
 
-- 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.
+Use the `only:variables` or `except:variables` keywords to control when to add jobs
+to a pipeline, based on the status of [CI/CD variables](../variables/index.md).
 
-**Example of `dast_configuration`**:
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-```yaml
-stages:
-  - build
-  - dast
+**Possible inputs**: An array of [CI/CD variable expressions](../jobs/job_control.md#cicd-variable-expressions).
 
-include:
-  - template: DAST.gitlab-ci.yml
+**Example of `only:variables`**:
 
-dast:
-  dast_configuration:
-    site_profile: "Example Co"
-    scanner_profile: "Quick Passive Test"
+```yaml
+deploy:
+  script: cap staging deploy
+  only:
+    variables:
+      - $RELEASE == "staging"
+      - $STAGING
 ```
 
-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).
+- [`only:variables` and `except:variables` examples](../jobs/job_control.md#only-variables--except-variables-examples).
 
-### `retry`
+#### `only:changes` / `except:changes`
 
-Use `retry` to configure how many times a job is retried if it fails.
-If not defined, defaults to `0` and jobs do not retry.
+Use the `changes` keyword with `only` to run a job, or with `except` to skip a job,
+when a Git push event modifies a file.
 
-When a job fails, the job is processed up to two more times, until it succeeds or
-reaches the maximum number of retries.
+Use `changes` in pipelines with the following refs:
 
-By default, all failure types cause the job to be retried. Use [`retry:when`](#retrywhen)
-to select which failures to retry on.
+- `branches`
+- `external_pull_requests`
+- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests))
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-**Possible inputs**: `0` (default), `1`, or `2`.
+**Possible inputs**: An array including any number of:
 
-**Example of `retry`**:
+- Paths to files.
+- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory
+  and all its subdirectories, for example `path/to/directory/**/*`.
+- Wildcard ([glob](https://en.wikipedia.org/wiki/Glob_(programming))) paths for all
+  files with the same extension or multiple extensions, for example `*.md` or `path/to/directory/*.{rb,py,sh}`.
+- Wildcard paths to files in the root directory, or all directories, wrapped in double quotes.
+  For example `"*.json"` or `"**/*.json"`.
+
+**Example of `only:changes`**:
 
 ```yaml
-test:
-  script: rspec
-  retry: 2
+docker build:
+  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
+  only:
+    refs:
+      - branches
+    changes:
+      - Dockerfile
+      - docker/scripts/*
+      - dockerfiles/**/*
+      - more_scripts/*.{rb,py,sh}
+      - "**/*.json"
 ```
 
-#### `retry:when`
-
-Use `retry:when` with `retry:max` to retry jobs for only specific failure cases.
-`retry:max` is the maximum number of retries, like [`retry`](#retry), and can be
-`0`, `1`, or `2`.
+**Additional details**:
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+- `changes` resolves to `true` if any of the matching files are changed (an `OR` operation).
+- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`,
+  `changes` can't determine if a given file is new or old and always returns `true`.
+- If you use `only: changes` with other refs, jobs ignore the changes and always run.
+- If you use `except: changes` with other refs, jobs ignore the changes and never run.
 
-**Possible inputs**: A single failure type, or an array of one or more failure types:
+**Related topics**:
 
-<!--
-  If you change any of the values below, make sure to update the `RETRY_WHEN_IN_DOCUMENTATION`
-  array in `spec/lib/gitlab/ci/config/entry/retry_spec.rb`.
-  The test there makes sure that all documented
-  values are valid as a configuration option and therefore should always
-  stay in sync with this documentation.
--->
+- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples).
+- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds),
+  you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests).
+- Use `changes` with [new branches or tags *without* pipelines for merge requests](../jobs/job_control.md#use-onlychanges-without-pipelines-for-merge-requests).
+- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines).
 
-- `always`: Retry on any failure (default).
-- `unknown_failure`: Retry when the failure reason is unknown.
-- `script_failure`: Retry when the script failed.
-- `api_failure`: Retry on API failure.
-- `stuck_or_timeout_failure`: Retry when the job got stuck or timed out.
-- `runner_system_failure`: Retry if there is a runner system failure (for example, job setup failed).
-- `runner_unsupported`: Retry if the runner is unsupported.
-- `stale_schedule`: Retry if a delayed job could not be executed.
-- `job_execution_timeout`: Retry if the script exceeded the maximum execution time set for the job.
-- `archived_failure`: Retry if the job is archived and can't be run.
-- `unmet_prerequisites`: Retry if the job failed to complete prerequisite tasks.
-- `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner.
-- `data_integrity_failure`: Retry if there is a structural integrity problem detected.
+#### `only:kubernetes` / `except:kubernetes`
 
-**Example of `retry:when`** (single failure type):
+Use `only:kubernetes` or `except:kubernetes` to control if jobs are added to the pipeline
+when the Kubernetes service is active in the project.
 
-```yaml
-test:
-  script: rspec
-  retry:
-    max: 2
-    when: runner_system_failure
-```
+**Keyword type**: Job-specific. You can use it only as part of a job.
 
-If there is a failure other than a runner system failure, the job is not retried.
+**Possible inputs**: The `kubernetes` strategy accepts only the `active` keyword.
 
-**Example of `retry:when`** (array of failure types):
+**Example of `only:kubernetes`**:
 
 ```yaml
-test:
-  script: rspec
-  retry:
-    max: 2
-    when:
-      - runner_system_failure
-      - stuck_or_timeout_failure
+deploy:
+  only:
+    kubernetes: active
 ```
 
-**Related topics**:
-
-You can specify the number of [retry attempts for certain stages of job execution](../runners/configure_runners.md#job-stages-attempts)
-using variables.
-
-### `timeout`
+In this example, the `deploy` job runs only when the Kubernetes service is active
+in the project.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3.
+### `pages`
 
-Use `timeout` to configure a timeout for a specific job. If the job runs for longer
-than the timeout, the job fails.
+Use `pages` to define a [GitLab Pages](../../user/project/pages/index.md) job that
+uploads static content to GitLab. The content is then published as a website.
 
-The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run).
-but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner).
+**Keyword type**: Job name.
 
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
+**Example of `pages`**:
 
-**Possible inputs**: A period of time written in natural language. For example, these are all equivalent:
+```yaml
+pages:
+  stage: deploy
+  script:
+    - mkdir .public
+    - cp -r * .public
+    - mv .public public
+  artifacts:
+    paths:
+      - public
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
 
-- `3600 seconds`
-- `60 minutes`
-- `one hour`
+This example moves all files from the root of the project to the `public/` directory.
+The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop.
 
-**Example of `timeout`**:
+**Additional details**:
 
-```yaml
-build:
-  script: build.sh
-  timeout: 3 hours 30 minutes
+You must:
 
-test:
-  script: rspec
-  timeout: 3h 30m
-```
+- Place any static content in a `public/` directory.
+- Define [`artifacts`](#artifacts) with a path to the `public/` directory.
 
 ### `parallel`
 
@@ -3217,175 +2683,6 @@ deploystacks: [vultr, processing]
 - [Run a one-dimensional matrix of parallel jobs](../jobs/job_control.md#run-a-one-dimensional-matrix-of-parallel-jobs).
 - [Run a matrix of triggered parallel jobs](../jobs/job_control.md#run-a-matrix-of-parallel-trigger-jobs).
 
-### `trigger`
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in GitLab Premium 11.8.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8.
-
-Use `trigger` to start a downstream pipeline that is either:
-
-- [A multi-project pipeline](../pipelines/multi_project_pipelines.md).
-- [A child pipeline](../pipelines/parent_child_pipelines.md).
-
-**Keyword type**: Job keyword. You can use it only as part of a job.
-
-**Possible inputs**: 
-
-- For multi-project pipelines, path to the downstream project.
-- For child pipelines, path to the child pipeline CI/CD configuration file.
-
-**Example of `trigger` for multi-project pipeline**:
-
-```yaml
-rspec:
-  stage: test
-  script: bundle exec rspec
-
-staging:
-  stage: deploy
-  trigger: my/deployment
-```
-
-**Example of `trigger` for child pipelines**:
-
-```yaml
-trigger_job:
-  trigger:
-    include: path/to/child-pipeline.yml
-```
-
-**Additional details**:
-
-- Jobs with `trigger` can only use a [limited set of keywords](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file).
-  For example, you can't run commands with [`script`](#script), [`before_script`](#before_script),
-  or [`after_script`](#after_script).
-- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you
-  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`.
-- In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can
-  view which job triggered a downstream pipeline in the [pipeline graph](../pipelines/index.md#visualize-pipelines).
-
-**Related topics**:
-
-- [Multi-project pipeline configuration examples](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file).
-- [Child pipeline configuration examples](../pipelines/parent_child_pipelines.md#examples).
-- To force a rebuild of a specific branch, tag, or commit, you can
-  [use an API call with a trigger token](../triggers/index.md).
-  The trigger token is different than the `trigger` keyword.
-
-#### `trigger:strategy`
-
-Use `trigger:strategy` to force the `trigger` job to wait for the downstream pipeline to complete
-before it is marked as **success**.
-
-This behavior is different than the default, which is for the `trigger` job to be marked as
-**success** as soon as the downstream pipeline is created.
-
-This setting makes your pipeline execution linear rather than parallel.
-
-**Example of `trigger:strategy`**:
-
-```yaml
-trigger_job:
-  trigger:
-    include: path/to/child-pipeline.yml
-    strategy: depend
-```
-
-In this example, jobs from subsequent stages wait for the triggered pipeline to
-successfully complete before starting. 
-
-### `interruptible`
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3.
-
-Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes.
-
-This keyword is used with the [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines)
-feature. When enabled, a running job with `interruptible: true` can be cancelled when
-a new pipeline starts on the same branch.
-
-You can't cancel subsequent jobs after a job with `interruptible: false` starts.
-
-**Keyword type**: Job keyword. You can use it only as part of a job or in the
-[`default:` section](#default).
-
-**Possible inputs**: `true` or `false` (default).
-
-**Example of `interruptible`**:
-
-```yaml
-stages:
-  - stage1
-  - stage2
-  - stage3
-
-step-1:
-  stage: stage1
-  script:
-    - echo "Can be canceled."
-  interruptible: true
-
-step-2:
-  stage: stage2
-  script:
-    - echo "Can not be canceled."
-
-step-3:
-  stage: stage3
-  script:
-    - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible."
-  interruptible: true
-```
-
-In this example, a new pipeline causes a running pipeline to be:
-
-- Canceled, if only `step-1` is running or pending.
-- Not canceled, after `step-2` starts.
-
-**Additional details**:
-
-- Only set `interruptible: true` if the job can be safely canceled after it has started,
-  like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments.
-- To completely cancel a running pipeline, all jobs must have `interruptible: true`,
-  or `interruptible: false` jobs must not have started.
-
-### `resource_group`
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7.
-
-Use `resource_group` to create a [resource group](../resource_groups/index.md) that
-ensures a job is mutually exclusive across different pipelines for the same project.
-
-For example, if multiple jobs that belong to the same resource group are queued simultaneously,
-only one of the jobs starts. The other jobs wait until the `resource_group` is free.
-
-Resource groups behave similar to semaphores in other programming languages.
-
-You can define multiple resource groups per environment. For example,
-when deploying to physical devices, you might have multiple physical devices. Each device
-can be deployed to, but only one deployment can occur per device at any given time.
-
-**Keyword type**: Job keyword. You can use it only as part of a job.
-
-**Possible inputs**: Only letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces.
-It can't start or end with `/`.
-
-**Example of `resource_group`**:
-
-```yaml
-deploy-to-production:
-  script: deploy
-  resource_group: production
-```
-
-In this example, two `deploy-to-production` jobs in two separate pipelines can never run at the same time. As a result,
-you can ensure that concurrent deployments never happen to the production environment.
-
-**Related topics**:
-
-- [Pipeline-level concurrency control with cross-project/parent-child pipelines](../resource_groups/index.md#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines).
-
 ### `release`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 13.2.
@@ -3589,6 +2886,390 @@ assets:
       link_type: 'other' # optional
 ```
 
+### `resource_group`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7.
+
+Use `resource_group` to create a [resource group](../resource_groups/index.md) that
+ensures a job is mutually exclusive across different pipelines for the same project.
+
+For example, if multiple jobs that belong to the same resource group are queued simultaneously,
+only one of the jobs starts. The other jobs wait until the `resource_group` is free.
+
+Resource groups behave similar to semaphores in other programming languages.
+
+You can define multiple resource groups per environment. For example,
+when deploying to physical devices, you might have multiple physical devices. Each device
+can be deployed to, but only one deployment can occur per device at any given time.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: Only letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces.
+It can't start or end with `/`.
+
+**Example of `resource_group`**:
+
+```yaml
+deploy-to-production:
+  script: deploy
+  resource_group: production
+```
+
+In this example, two `deploy-to-production` jobs in two separate pipelines can never run at the same time. As a result,
+you can ensure that concurrent deployments never happen to the production environment.
+
+**Related topics**:
+
+- [Pipeline-level concurrency control with cross-project/parent-child pipelines](../resource_groups/index.md#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines).
+
+### `retry`
+
+Use `retry` to configure how many times a job is retried if it fails.
+If not defined, defaults to `0` and jobs do not retry.
+
+When a job fails, the job is processed up to two more times, until it succeeds or
+reaches the maximum number of retries.
+
+By default, all failure types cause the job to be retried. Use [`retry:when`](#retrywhen)
+to select which failures to retry on.
+
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
+
+**Possible inputs**: `0` (default), `1`, or `2`.
+
+**Example of `retry`**:
+
+```yaml
+test:
+  script: rspec
+  retry: 2
+```
+
+#### `retry:when`
+
+Use `retry:when` with `retry:max` to retry jobs for only specific failure cases.
+`retry:max` is the maximum number of retries, like [`retry`](#retry), and can be
+`0`, `1`, or `2`.
+
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
+
+**Possible inputs**: A single failure type, or an array of one or more failure types:
+
+<!--
+  If you change any of the values below, make sure to update the `RETRY_WHEN_IN_DOCUMENTATION`
+  array in `spec/lib/gitlab/ci/config/entry/retry_spec.rb`.
+  The test there makes sure that all documented
+  values are valid as a configuration option and therefore should always
+  stay in sync with this documentation.
+-->
+
+- `always`: Retry on any failure (default).
+- `unknown_failure`: Retry when the failure reason is unknown.
+- `script_failure`: Retry when the script failed.
+- `api_failure`: Retry on API failure.
+- `stuck_or_timeout_failure`: Retry when the job got stuck or timed out.
+- `runner_system_failure`: Retry if there is a runner system failure (for example, job setup failed).
+- `runner_unsupported`: Retry if the runner is unsupported.
+- `stale_schedule`: Retry if a delayed job could not be executed.
+- `job_execution_timeout`: Retry if the script exceeded the maximum execution time set for the job.
+- `archived_failure`: Retry if the job is archived and can't be run.
+- `unmet_prerequisites`: Retry if the job failed to complete prerequisite tasks.
+- `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner.
+- `data_integrity_failure`: Retry if there is a structural integrity problem detected.
+
+**Example of `retry:when`** (single failure type):
+
+```yaml
+test:
+  script: rspec
+  retry:
+    max: 2
+    when: runner_system_failure
+```
+
+If there is a failure other than a runner system failure, the job is not retried.
+
+**Example of `retry:when`** (array of failure types):
+
+```yaml
+test:
+  script: rspec
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+```
+
+**Related topics**:
+
+You can specify the number of [retry attempts for certain stages of job execution](../runners/configure_runners.md#job-stages-attempts)
+using variables.
+
+### `rules`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3.
+
+Use `rules` to include or exclude jobs in pipelines.
+
+Rules are evaluated when the pipeline is created, and evaluated *in order*
+until the first match. When a match is found, the job is either included or excluded from the pipeline,
+depending on the configuration.
+
+You cannot use dotenv variables created in job scripts in rules, because rules are evaluated before any jobs run.
+
+`rules` replaces [`only/except`](#only--except) and they can't be used together
+in the same job. If you configure one job to use both keywords, the GitLab returns
+a `key may not be used with rules` error.
+
+`rules` accepts an array of rules defined with:
+
+- `if`
+- `changes`
+- `exists`
+- `allow_failure`
+- `variables`
+- `when`
+
+You can combine multiple keywords together for [complex rules](../jobs/job_control.md#complex-rules).
+
+The job is added to the pipeline:
+
+- If an `if`, `changes`, or `exists` rule matches and also has `when: on_success` (default),
+  `when: delayed`, or `when: always`.
+- If a rule is reached that is only `when: on_success`, `when: delayed`, or `when: always`.
+
+The job is not added to the pipeline:
+
+- If no rules match.
+- If a rule matches and has `when: never`.
+
+You can use [`!reference` tags](yaml_optimization.md#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs)
+in different jobs.
+
+#### `rules:if`
+
+Use `rules:if` clauses to specify when to add a job to a pipeline:
+
+- If an `if` statement is true, add the job to the pipeline.
+- If an `if` statement is true, but it's combined with `when: never`, do not add the job to the pipeline.
+- If no `if` statements are true, do not add the job to the pipeline.
+
+`if:` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md)
+or [custom CI/CD variables](../variables/index.md#custom-cicd-variables).
+
+**Keyword type**: Job-specific and pipeline-specific. You can use it as part of a job
+to configure the job behavior, or with [`workflow`](#workflow) to configure the pipeline behavior.
+
+**Possible inputs**: A [CI/CD variable expression](../jobs/job_control.md#cicd-variable-expressions).
+
+**Example of `rules:if`**:
+
+```yaml
+job:
+  script: echo "Hello, Rules!"
+  rules:
+    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH'
+      when: never
+    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/'
+      when: manual
+      allow_failure: true
+    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
+```
+
+**Additional details**:
+
+- If a rule matches and has no `when` defined, the rule uses the `when`
+  defined for the job, which defaults to `on_success` if not defined.
+- You can define `when` once per rule, or once at the job-level, which applies to
+  all rules. You can't mix `when` at the job-level with `when` in rules.
+- Unlike variables in [`script`](../variables/index.md#use-cicd-variables-in-job-scripts)
+  sections, variables in rules expressions are always formatted as `$VARIABLE`.
+  - You can use `rules:if` with `include` to [conditionally include other configuration files](includes.md#use-rules-with-include).
+
+**Related topics**:
+
+- [Common `if` expressions for `rules`](../jobs/job_control.md#common-if-clauses-for-rules).
+- [Avoid duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines).
+
+#### `rules:changes`
+
+Use `rules:changes` to specify when to add a job to a pipeline by checking for changes
+to specific files.
+
+WARNING:
+You should use `rules: changes` only with **branch pipelines** or **merge request pipelines**.
+You can use `rules: changes` with other pipeline types, but `rules: changes` always
+evaluates to true when there is no Git `push` event. Tag pipelines, scheduled pipelines,
+and so on do **not** have a Git `push` event associated with them. A `rules: changes` job
+is **always** added to those pipelines if there is no `if:` that limits the job to
+branch or merge request pipelines.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: An array of file paths. In GitLab 13.6 and later,
+[file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges).
+
+**Example of `rules:changes`**:
+
+```yaml
+docker build:
+  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      changes:
+        - Dockerfile
+      when: manual
+      allow_failure: true
+```
+
+- If the pipeline is a merge request pipeline, check `Dockerfile` for changes.
+- If `Dockerfile` has changed, add the job to the pipeline as a manual job, and the pipeline
+  continues running even if the job is not triggered (`allow_failure: true`).
+- If `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`).
+
+**Additional details**:
+
+- `rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychanges--exceptchanges).
+- You can use `when: never` to implement a rule similar to [`except:changes`](#onlychanges--exceptchanges).
+- `changes` resolves to `true` if any of the matching files are changed (an `OR` operation).
+
+#### `rules:exists`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4.
+
+Use `exists` to run a job when certain files exist in the repository.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: An array of file paths. Paths are relative to the project directory (`$CI_PROJECT_DIR`)
+and can't directly link outside it. File paths can use glob patterns.
+
+**Example of `rules:exists`**:
+
+```yaml
+job:
+  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
+  rules:
+    - exists:
+        - Dockerfile
+```
+
+`job` runs if a `Dockerfile` exists anywhere in the repository.
+
+**Additional details**:
+
+- Glob patterns are interpreted with Ruby [`File.fnmatch`](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch)
+  with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`.
+- For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns or
+  file paths. After the 10,000th check, rules with patterned globs always match.
+  In other words, the `exists` rule always assumes a match in projects with more
+  than 10,000 files.
+- `exists` resolves to `true` if any of the listed files are found (an `OR` operation).
+
+#### `rules:allow_failure`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8.
+
+Use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail
+without stopping the pipeline.
+
+You can also use `allow_failure: true` with a manual job. The pipeline continues
+running without waiting for the result of the manual job. `allow_failure: false`
+combined with `when: manual` in rules causes the pipeline to wait for the manual
+job to run before continuing.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: `true` or `false`. Defaults to `false` if not defined.
+
+**Example of `rules:allow_failure`**:
+
+```yaml
+job:
+  script: echo "Hello, Rules!"
+  rules:
+    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
+      when: manual
+      allow_failure: true
+```
+
+If the rule matches, then the job is a manual job with `allow_failure: true`.
+
+**Additional details**:
+
+- The rule-level `rules:allow_failure` overrides the job-level [`allow_failure`](#allow_failure),
+  and only applies when the specific rule triggers the job.
+
+#### `rules:variables`
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209864) in GitLab 13.7.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289803) in GitLab 13.10.
+
+Use [`variables`](#variables) in `rules:` to define variables for specific conditions.
+
+**Keyword type**: Job-specific. You can use it only as part of a job.
+
+**Possible inputs**: A hash of variables in the format `VARIABLE-NAME: value`.
+
+**Example of `rules:variables`**:
+
+```yaml
+job:
+  variables:
+    DEPLOY_VARIABLE: "default-deploy"
+  rules:
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+      variables:                              # Override DEPLOY_VARIABLE defined
+        DEPLOY_VARIABLE: "deploy-production"  # at the job level.
+    - if: $CI_COMMIT_REF_NAME =~ /feature/
+      variables:
+        IS_A_FEATURE: "true"                  # Define a new variable.
+  script:
+    - echo "Run script with $DEPLOY_VARIABLE as an argument"
+    - echo "Run another script if $IS_A_FEATURE exists"
+```
+
+### `script`
+
+Use `script` to specify commands for the runner to execute.
+
+All jobs except [trigger jobs](#trigger) require a `script` keyword.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: An array including:
+
+- Single line commands.
+- Long commands [split over multiple lines](script.md#split-long-commands).
+- [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts).
+
+**Example of `script`:**
+
+```yaml
+job1:
+  script: "bundle exec rspec"
+
+job2:
+  script:
+    - uname -a
+    - bundle exec rspec
+```
+
+**Additional details**:
+
+- When you use [these special characters in `script`](script.md#use-special-characters-with-script), you must use single quotes (`'`) or double quotes (`"`) .
+
+**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.
+
 ### `secrets` **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) in GitLab 13.4.
@@ -3683,118 +3364,322 @@ job:
 - The `file` keyword is a setting for the CI/CD variable and must be nested under
   the CI/CD variable name, not in the `vault` section.
 
-### `pages`
+### `services`
 
-Use `pages` to define a [GitLab Pages](../../user/project/pages/index.md) job that
-uploads static content to GitLab. The content is then published as a website.
+Use `services` to specify an additional Docker image to run scripts in. The [`services` image](../services/index.md) is linked
+to the image specified in the [`image`](#image) keyword.
 
-**Keyword type**: Job name.
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-**Example of `pages`**:
+**Possible inputs**: The name of the services image, including the registry path if needed, in one of these formats:
+
+- `<image-name>` (Same as using `<image-name>` with the `latest` tag)
+- `<image-name>:<tag>`
+- `<image-name>@<digest>`
+
+**Example of `services`**:
 
 ```yaml
-pages:
-  stage: deploy
+default:
+  image:
+    name: ruby:2.6
+    entrypoint: ["/bin/bash"]
+
+  services:
+    - name: my-postgres:11.7
+      alias: db-postgres
+      entrypoint: ["/usr/local/bin/db-postgres"]
+      command: ["start"]
+
+  before_script:
+    - bundle install
+
+test:
   script:
-    - mkdir .public
-    - cp -r * .public
-    - mv .public public
-  artifacts:
-    paths:
-      - public
-  rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - bundle exec rake spec
 ```
 
-This example moves all files from the root of the project to the `public/` directory.
-The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop.
+In this example, the job launches a Ruby container. Then, from that container, the job launches
+another container that's running PostgreSQL. Then the job then runs scripts
+in that container.
+
+**Related topics**:
+
+- [Available settings for `services`](../services/index.md#available-settings-for-services).
+- [Define `services` in the `.gitlab-ci.yml` file](../services/index.md#define-services-in-the-gitlab-ciyml-file).
+- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md).
+- [Use Docker to build Docker images](../docker/using_docker_build.md).
+
+### `stage`
+
+Use `stage` to define which [stage](#stages) a job runs in. Jobs in the same
+`stage` can execute in parallel (see **Additional details**).
+
+If `stage` is not defined, the job uses the `test` stage by default.
+
+**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:
+  - build
+  - test
+  - deploy
+
+job1:
+  stage: build
+  script:
+    - echo "This job compiles code."
+
+job2:
+  stage: test
+  script:
+    - echo "This job tests the compiled code. It runs when the build stage completes."
+
+job3:
+  script:
+    - echo "This job also runs in the test stage".
+
+job4:
+  stage: deploy
+  script:
+    - echo "This job deploys the code. It runs when the test stage completes."
+```
 
 **Additional details**:
 
-You must:
+- 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`.
 
-- Place any static content in a `public/` directory.
-- Define [`artifacts`](#artifacts) with a path to the `public/` directory.
+#### `stage: .pre`
 
-### `inherit`
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9.
+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 have to define `.pre` in [`stages`](#stages).
 
-Use `inherit:` to [control inheritance of globally-defined defaults and variables](../jobs/index.md#control-the-inheritance-of-default-keywords-and-global-variables).
+You must have a job in at least one stage other than `.pre` or `.post`.
 
-#### `inherit:default`
+**Keyword type**: You can only use it with a job's `stage` keyword.
 
-Use `inherit:default` to control the inheritance of [default keywords](#default).
+**Example of `stage: .pre`**:
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+```yaml
+stages:
+  - build
+  - test
 
-**Possible inputs**:
+job1:
+  stage: build
+  script:
+    - echo "This job runs in the build stage."
 
-- `true` (default) or `false` to enable or disable the inheritance of all default keywords.
-- A list of specific default keywords to inherit.
+first-job:
+  stage: .pre
+  script:
+    - echo "This job runs in the .pre stage, before all other stages."
 
-**Example of `inherit:default`:**
+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 have 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
-default:
-  retry: 2
-  image: ruby:3.0
-  interruptible: true
+stages:
+  - build
+  - test
 
 job1:
-  script: echo "This job does not inherit any default keywords."
-  inherit:
-    default: false
+  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:
-  script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'."
-  inherit:
-    default:
-      - retry
-      - image
+  stage: test
+  script:
+    - echo "This job runs in the test stage."
 ```
 
-**Additional details:**
+### `tags`
 
-- You can also list default keywords to inherit on one line: `default: [keyword1, keyword2]`
+> - A limit of 50 tags per job [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338929) in GitLab 14.3.
+> - A limit of 50 tags per job [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/339855) in GitLab 14.3.
 
-#### `inherit:variables`
+Use `tags` to select a specific runner from the list of all runners that are
+available for the project.
 
-Use `inherit:variables` to control the inheritance of [global variables](#variables) keywords.
+When you register a runner, you can specify the runner's tags, for
+example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner must
+be assigned every tag listed in the job.
 
-**Keyword type**: Job keyword. You can use it only as part of a job.
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
 **Possible inputs**:
 
-- `true` (default) or `false` to enable or disable the inheritance of all global variables.
-- A list of specific variables to inherit.
+- An array of tag names.
+- [CI/CD variables](../runners/configure_runners.md#use-cicd-variables-in-tags) in GitLab 14.1 and later.
 
-**Example of `inherit:variables`:**
+**Example of `tags`**:
 
 ```yaml
-variables:
-  VARIABLE1: "This is variable 1"
-  VARIABLE2: "This is variable 2"
-  VARIABLE3: "This is variable 3"
+job:
+  tags:
+    - ruby
+    - postgres
+```
 
-job1:
-  script: echo "This job does not inherit any global variables."
-  inherit:
-    variables: false
+In this example, only runners with *both* the `ruby` and `postgres` tags can run the job.
 
-job2:
-  script: echo "This job inherits only the two listed global variables. It does not inherit 'VARIABLE3'."
-  inherit:
-    variables:
-      - VARIABLE1
-      - VARIABLE2
+**Additional details**:
+
+- In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later,
+  the number of tags must be less than `50`.
+
+**Related topics**:
+
+- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run).
+
+### `timeout`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3.
+
+Use `timeout` to configure a timeout for a specific job. If the job runs for longer
+than the timeout, the job fails.
+
+The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run).
+but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner).
+
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
+
+**Possible inputs**: A period of time written in natural language. For example, these are all equivalent:
+
+- `3600 seconds`
+- `60 minutes`
+- `one hour`
+
+**Example of `timeout`**:
+
+```yaml
+build:
+  script: build.sh
+  timeout: 3 hours 30 minutes
+
+test:
+  script: rspec
+  timeout: 3h 30m
 ```
 
-**Additional details:**
+### `trigger`
 
-- You can also list global variables to inherit on one line: `variables: [VARIABLE1, VARIABLE2]`
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in GitLab Premium 11.8.
+> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8.
+
+Use `trigger` to start a downstream pipeline that is either:
+
+- [A multi-project pipeline](../pipelines/multi_project_pipelines.md).
+- [A child pipeline](../pipelines/parent_child_pipelines.md).
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: 
+
+- For multi-project pipelines, path to the downstream project.
+- For child pipelines, path to the child pipeline CI/CD configuration file.
+
+**Example of `trigger` for multi-project pipeline**:
+
+```yaml
+rspec:
+  stage: test
+  script: bundle exec rspec
+
+staging:
+  stage: deploy
+  trigger: my/deployment
+```
 
-## `variables`
+**Example of `trigger` for child pipelines**:
+
+```yaml
+trigger_job:
+  trigger:
+    include: path/to/child-pipeline.yml
+```
+
+**Additional details**:
+
+- Jobs with `trigger` can only use a [limited set of keywords](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file).
+  For example, you can't run commands with [`script`](#script), [`before_script`](#before_script),
+  or [`after_script`](#after_script).
+- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you
+  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`.
+- In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can
+  view which job triggered a downstream pipeline in the [pipeline graph](../pipelines/index.md#visualize-pipelines).
+
+**Related topics**:
+
+- [Multi-project pipeline configuration examples](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file).
+- [Child pipeline configuration examples](../pipelines/parent_child_pipelines.md#examples).
+- To force a rebuild of a specific branch, tag, or commit, you can
+  [use an API call with a trigger token](../triggers/index.md).
+  The trigger token is different than the `trigger` keyword.
+
+#### `trigger:strategy`
+
+Use `trigger:strategy` to force the `trigger` job to wait for the downstream pipeline to complete
+before it is marked as **success**.
+
+This behavior is different than the default, which is for the `trigger` job to be marked as
+**success** as soon as the downstream pipeline is created.
+
+This setting makes your pipeline execution linear rather than parallel.
+
+**Example of `trigger:strategy`**:
+
+```yaml
+trigger_job:
+  trigger:
+    include: path/to/child-pipeline.yml
+    strategy: depend
+```
+
+In this example, jobs from subsequent stages wait for the triggered pipeline to
+successfully complete before starting.
+
+### `variables`
 
 [CI/CD variables](../variables/index.md) are configurable values that are passed to jobs.
 Use `variables` to create [custom variables](../variables/index.md#custom-cicd-variables).
@@ -3846,7 +3731,7 @@ deploy_review_job:
   automatically creates and makes available in the job.
 - You can [configure runner behavior with variables](../runners/configure_runners.md#configure-runner-behavior-with-variables).
 
-### `variables:description`
+#### `variables:description`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7.
 
@@ -3868,6 +3753,84 @@ variables:
     description: "The deployment target. Change this variable to 'canary' or 'production' if needed."
 ```
 
+### `when`
+
+Use `when` to configure the conditions for when jobs run. If not defined in a job,
+the default value is `when: on_success`.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**:
+
+- `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.
+
+**Example of `when`**:
+
+```yaml
+stages:
+  - build
+  - cleanup_build
+  - test
+  - deploy
+  - cleanup
+
+build_job:
+  stage: build
+  script:
+    - make build
+
+cleanup_build_job:
+  stage: cleanup_build
+  script:
+    - cleanup build when failed
+  when: on_failure
+
+test_job:
+  stage: test
+  script:
+    - make test
+
+deploy_job:
+  stage: deploy
+  script:
+    - make deploy
+  when: manual
+
+cleanup_job:
+  stage: cleanup
+  script:
+    - cleanup after jobs
+  when: always
+```
+
+In this example, the script:
+
+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.
+
+**Additional details**:
+
+- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), 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`.
+
+**Related topics**:
+
+- `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.
+
 ## Deprecated keywords
 
 The following keywords are deprecated.
diff --git a/doc/development/work_items_widgets.md b/doc/development/work_items_widgets.md
new file mode 100644
index 00000000000..92919c10a9f
--- /dev/null
+++ b/doc/development/work_items_widgets.md
@@ -0,0 +1,114 @@
+---
+stage: Plan
+group: Project Management
+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
+---
+# Work items widgets
+
+## Frontend architecture
+
+Widgets for work items are heavily inspired by [Frontend widgets](fe_guide/widgets.md).
+You can expect some differences, because work items are architecturally different from issuables.
+
+GraphQL (Vue Apollo) constitutes the core of work items widgets' stack.
+
+### Retrieve widget information for work items
+
+To display a work item page, the frontend must know which widgets are available
+on the work item it is attempting to display. To do so, it needs to fetch the
+list of widgets, using a query like this:
+
+```plaintext
+query WorkItem($workItemId: ID!) {
+  workItem(workItemId: $id) @client {
+    id
+    type
+    widgets {
+      nodes {
+        type
+      }
+    }
+  }
+}
+```
+
+### GraphQL queries and mutations
+
+GraphQL queries and mutations are work item agnostic. Work item queries and mutations
+should happen at the widget level, so widgets are standalone reusable components.
+The work item query and mutation should support any work item type and be dynamic.
+They should allow you to query and mutate any work item attribute by specifying a widget identifier.
+
+In this query example, the description widget uses the query and mutation to
+display and update the description of any work item:
+
+```plaintext
+query {
+  workItem(input: {
+    workItemId: "gid://gitlab/AnyWorkItem/2207",
+    widgetIdentifier: "description",
+  }) {
+    id
+    type
+    widgets {
+      nodes {
+        ... on DescriptionWidget {
+          contentText
+        }
+      }
+    }
+  }
+}
+
+```
+
+Mutation example:
+
+```plaintext
+mutation {
+  updateWorkItem(input: {
+    workItemId: "gid://gitlab/AnyWorkItem/2207",
+    widgetIdentifier: "description",
+    value: "the updated description"
+  }) {
+    workItem {
+      id
+      description
+    }
+  }
+}
+
+```
+
+### Widget's responsibility and structure
+
+A widget is responsible for displaying and updating a single attribute, such as
+title, description, or labels. Widgets must support any type of work item.
+To maximize component reusability, widgets should be field wrappers owning the
+work item query and mutation of the attribute it's responsible for.
+
+A field component is a generic and simple component. It has no knowledge of the
+attribute or work item details, such as input field, date selector, or dropdown.
+
+Widgets must be configurable to support various use cases, depending on work items.
+When building widgets, use slots to provide extra context while minimizing
+the use of props and injected attributes.
+
+### Examples
+
+We have a [dropdown field component](https://gitlab.com/gitlab-org/gitlab/-/blob/eea9ad536fa2d28ee6c09ed7d9207f803142eed7/app/assets/javascripts/vue_shared/components/dropdown/dropdown_widget/dropdown_widget.vue)
+for use as reference.
+
+Any work item widget can wrap the dropdown component. The widget has knowledge of
+the attribute it mutates, and owns the mutation for it. Multiple widgets can use
+the same field component. For example:
+
+- Title and description widgets use the input field component.
+- Start and end date use the date selector component.
+- Labels, milestones, and assignees selectors use the dropdown component.
+
+Some frontend widgets already use the dropdown component. Use them as a reference
+for work items widgets development:
+
+- `ee/app/assets/javascripts/boards/components/assignee_select.vue`
+- `ee/app/assets/javascripts/boards/components/milestone_select.vue`
diff --git a/doc/user/group/index.md b/doc/user/group/index.md
index f0e08301a1b..b9539644b51 100644
--- a/doc/user/group/index.md
+++ b/doc/user/group/index.md
@@ -563,6 +563,8 @@ You should consider these security implications before configuring IP address re
   requests a new job or an update to a job's state, it is also not bound by
   the IP restrictions. But when the running CI/CD job sends Git requests from a
   restricted IP address, the IP restriction prevents code from being cloned.
+- **User dashboard activity**: Users may still see some events from the IP restricted groups and projects
+  on their dashboard. Activity may include push, merge, issue, or comment events. 
 
 To restrict group access by IP address:
 
diff --git a/qa/qa/page/admin/settings/component/usage_statistics.rb b/qa/qa/page/admin/settings/component/usage_statistics.rb
new file mode 100644
index 00000000000..0275b7ae926
--- /dev/null
+++ b/qa/qa/page/admin/settings/component/usage_statistics.rb
@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module QA
+  module Page
+    module Admin
+      module Settings
+        module Component
+          class UsageStatistics < Page::Base
+            view 'app/views/admin/application_settings/_usage.html.haml' do
+              element :enable_usage_data_checkbox
+            end
+
+            def has_disabled_usage_data_checkbox?
+              has_element?(:enable_usage_data_checkbox, disabled: true)
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/qa/qa/page/admin/settings/metrics_and_profiling.rb b/qa/qa/page/admin/settings/metrics_and_profiling.rb
index 41fad942fc4..7224e51e110 100644
--- a/qa/qa/page/admin/settings/metrics_and_profiling.rb
+++ b/qa/qa/page/admin/settings/metrics_and_profiling.rb
@@ -9,6 +9,7 @@ module QA
 
           view 'app/views/admin/application_settings/metrics_and_profiling.html.haml' do
             element :performance_bar_settings_content
+            element :usage_statistics_settings_content
           end
 
           def expand_performance_bar(&block)
@@ -16,6 +17,12 @@ module QA
               Component::PerformanceBar.perform(&block)
             end
           end
+
+          def expand_usage_statistics(&block)
+            expand_content(:usage_statistics_settings_content) do
+              Component::UsageStatistics.perform(&block)
+            end
+          end
         end
       end
     end
diff --git a/qa/qa/specs/features/browser_ui/non_devops/service_ping_default_enabled_spec.rb b/qa/qa/specs/features/browser_ui/non_devops/service_ping_default_enabled_spec.rb
new file mode 100644
index 00000000000..ecc59aa7cc8
--- /dev/null
+++ b/qa/qa/specs/features/browser_ui/non_devops/service_ping_default_enabled_spec.rb
@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module QA
+  RSpec.describe 'Service ping default enabled' do
+    context 'When using default enabled from gitlab.yml config', :requires_admin do
+      before do
+        Flow::Login.sign_in_as_admin
+
+        Page::Main::Menu.perform(&:go_to_admin_area)
+        Page::Admin::Menu.perform(&:go_to_metrics_and_profiling_settings)
+      end
+
+      it 'has service ping toggle enabled' do
+        Page::Admin::Settings::MetricsAndProfiling.perform do |setting|
+          setting.expand_usage_statistics do |page|
+            expect(page).not_to have_disabled_usage_data_checkbox
+          end
+        end
+      end
+    end
+  end
+end