Add latest changes from gitlab-org/gitlab@14-6-stable-eev14.6.0-rc42

8 files changed, 222 insertions, 16 deletions

diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md
index 7ecee5508ef..e47b6dddc5f 100644
--- a/doc/ci/pipelines/job_artifacts.md
+++ b/doc/ci/pipelines/job_artifacts.md
@@ -48,7 +48,171 @@ is used.
 If you run two types of pipelines (like branch and scheduled) for the same ref,
 the pipeline that finishes later creates the job artifact.
 
-For more examples, view the [keyword reference for the `.gitlab-ci.yml` file](../yaml/index.md#artifacts).
+To disable artifact passing, define the job with empty [dependencies](../yaml/index.md#dependencies):
+
+```yaml
+job:
+  stage: build
+  script: make build
+  dependencies: []
+```
+
+You may want to create artifacts only for tagged releases to avoid filling the
+build server storage with temporary build artifacts. For example, use [`rules`](../yaml/index.md#rules)
+to create artifacts only for tags:
+
+```yaml
+default-job:
+  script:
+    - mvn test -U
+  rules:
+    - if: $CI_COMMIT_BRANCH
+
+release-job:
+  script:
+    - mvn package -U
+  artifacts:
+    paths:
+      - target/*.war
+  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`:
+
+```yaml
+job:
+  artifacts:
+    paths:
+      - path/*xyz/*
+```
+
+### Use CI/CD variables to define the artifacts name
+
+You can use [CI/CD variables](../variables/index.md) to dynamically define the
+artifacts file's name.
+
+For example, to create an archive with a name of the current job:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_JOB_NAME"
+    paths:
+      - binaries/
+```
+
+To create an archive with a name of the current branch or tag including only
+the binaries directory:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
+
+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.
+
+To create an archive with a name of the current job and the current branch or
+tag including only the binaries directory:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
+
+To create an archive with a name of the current [stage](../yaml/index.md#stages) and branch name:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
+
+If you use **Windows Batch** to run your shell scripts you must replace
+`$` with `%`:
+
+```yaml
+job:
+  artifacts:
+    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
+    paths:
+      - binaries/
+```
+
+If you use **Windows PowerShell** to run your shell scripts you must replace
+`$` with `$env:`:
+
+```yaml
+job:
+  artifacts:
+    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
+
+### Exclude files from job artifacts
+
+Use [`artifacts:exclude`](../yaml/index.md#artifactsexclude) to prevent files from
+being added to an artifacts archive.
+
+For example, to store all files in `binaries/`, but not `*.o` files located in
+subdirectories of `binaries/`.
+
+```yaml
+artifacts:
+  paths:
+    - binaries/
+  exclude:
+    - binaries/**/*.o
+```
+
+Unlike [`artifacts:paths`](../yaml/index.md#artifactspaths), `exclude` paths are not recursive.
+To exclude all of the contents of a directory, match them explicitly rather
+than matching the directory itself.
+
+For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory:
+
+```yaml
+artifacts:
+  paths:
+    - binaries/
+  exclude:
+    - binaries/temp/**/*
+```
+
+### Add untracked files to artifacts
+
+Use [`artifacts:untracked`](../yaml/index.md#artifactsuntracked) to add all Git untracked
+files as artifacts (along with the paths defined in [`artifacts:paths`](../yaml/index.md#artifactspaths)).
+
+Save all Git untracked files and files in `binaries`:
+
+```yaml
+artifacts:
+  untracked: true
+  paths:
+    - binaries/
+```
+
+Save all untracked files but [exclude](../yaml/index.md#artifactsexclude) `*.txt`:
+
+```yaml
+artifacts:
+  untracked: true
+  exclude:
+    - "*.txt"
+```
 
 ## Download job artifacts
 
@@ -103,6 +267,35 @@ To delete a job:
 1. On the top right of the job's log, select **Erase job log** (**{remove}**).
 1. On the confirmation dialog, select **OK**.
 
+## Expose job artifacts in the merge request UI
+
+Use the [`artifacts:expose_as`](../yaml/index.md#artifactsexpose_as) keyword to expose
+[job artifacts](../pipelines/job_artifacts.md) in the [merge request](../../user/project/merge_requests/index.md) UI.
+
+For example, to match a single file:
+
+```yaml
+test:
+  script: ["echo 'test' > file.txt"]
+  artifacts:
+    expose_as: 'artifact 1'
+    paths: ['file.txt']
+```
+
+With this configuration, GitLab adds a link **artifact 1** to the relevant merge request
+that points to `file.txt`. To access the link, select **View exposed artifact**
+below the pipeline graph in the merge request overview.
+
+An example that matches an entire directory:
+
+```yaml
+test:
+  script: ["mkdir test && echo 'test' > test/file.txt"]
+  artifacts:
+    expose_as: 'artifact 1'
+    paths: ['test/']
+```
+
 ## Retrieve job artifacts for other projects
 
 To retrieve a job artifact from a different project, you might need to use a
@@ -182,6 +375,14 @@ job artifacts are deleted.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4.
 > - [Made optional with a CI/CD setting](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8.
 
+By default artifacts are always kept for the most recent successful pipeline for
+each ref. This means that the latest artifacts do not immediately expire according
+to the `expire_in` specification.
+
+If a new pipeline for the same ref completes successfully, the previous pipeline's
+artifacts are deleted according to the `expire_in` configuration. The artifacts
+of the new pipeline are kept automatically.  
+
 Keeping the latest artifacts can use a large amount of storage space in projects
 with a lot of jobs or large artifacts. If the latest artifacts are not needed in
 a project, you can disable this behavior to save space:
@@ -194,9 +395,6 @@ a project, you can disable this behavior to save space:
 You can disable this behavior for all projects on a self-managed instance in the
 [instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
 
-When you disable the feature, the latest artifacts do not immediately expire.
-A new pipeline must run before the latest artifacts can expire and be deleted.
-
 ## Troubleshooting job artifacts
 
 ### Error message `No files to upload`
diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md
index 119633d38e2..85e5b62b0c4 100644
--- a/doc/ci/pipelines/merge_request_pipelines.md
+++ b/doc/ci/pipelines/merge_request_pipelines.md
@@ -112,11 +112,11 @@ C:
     - merge_requests
 ```
 
-- `A` and `B` always run, because they get the `only:` rule to execute in all cases.
+- `A` and `B` always run, because they get the `only` rule to execute in all cases.
 - `C` only runs for merge requests. It doesn't run for any pipeline
   except a merge request pipeline.
 
-In this example, you don't have to add the `only:` rule to all of your jobs to make
+In this example, you don't have to add the `only` rule to all of your jobs to make
 them always run. You can use this format to set up a Review App, which helps to
 save resources.
 
diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md
index 6074909a887..593cdb68b3f 100644
--- a/doc/ci/pipelines/merge_trains.md
+++ b/doc/ci/pipelines/merge_trains.md
@@ -11,6 +11,10 @@ last_update: 2019-07-03
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9186) in GitLab 12.0.
 > - [Squash and merge](../../user/project/merge_requests/squash_and_merge.md) support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13001) in GitLab 12.6.
 
+INFO:
+Get merge trains and more in GitLab Ultimate.
+[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-ci-cd-external-docs).
+
 For more information about why you might want to use merge trains, read [How merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/).
 
 When [pipelines for merged results](pipelines_for_merged_results.md) are
@@ -35,7 +39,8 @@ If the pipeline for the merge request at the front of the train completes succes
 the changes are merged into the target branch, and the other pipelines continue to
 run.
 
-To add a merge request to a merge train, you need [permissions](../../user/permissions.md) to push to the target branch.
+To add a merge request to a merge train, you need [permissions](../../user/permissions.md) to merge or push to the
+target branch.
 
 Each merge train can run a maximum of **twenty** pipelines in parallel.
 If more than twenty merge requests are added to the merge train, the merge requests
diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md
index 30b3bc2e277..8a83e7e31f4 100644
--- a/doc/ci/pipelines/multi_project_pipelines.md
+++ b/doc/ci/pipelines/multi_project_pipelines.md
@@ -213,7 +213,7 @@ In the upstream pipeline:
    ```
 
 1. Set the `test` job in the downstream pipeline to inherit the variables from the `build_vars`
-   job in the upstream project with `needs:`. The `test` job inherits the variables in the
+   job in the upstream project with `needs`. The `test` job inherits the variables in the
    `dotenv` report and it can access `BUILD_VERSION` in the script:
 
    ```yaml
diff --git a/doc/ci/pipelines/parent_child_pipelines.md b/doc/ci/pipelines/parent_child_pipelines.md
index 64f4160c963..5e4b707a38c 100644
--- a/doc/ci/pipelines/parent_child_pipelines.md
+++ b/doc/ci/pipelines/parent_child_pipelines.md
@@ -31,10 +31,9 @@ set of concurrently running child pipelines, but within the same project:
 - Child pipelines still execute each of their jobs according to a stage sequence, but
   would be free to continue forward through their stages without waiting for unrelated
   jobs in the parent pipeline to finish.
-- The configuration is split up into smaller child pipeline configurations, which are
+- The configuration is split up into smaller child pipeline configurations. Each child pipeline contains only relevant steps which are
   easier to understand. This reduces the cognitive load to understand the overall configuration.
 - Imports are done at the child pipeline level, reducing the likelihood of collisions.
-- Each pipeline has only relevant steps, making it easier to understand what's going on.
 
 Child pipelines work well with other GitLab CI/CD features:
 
@@ -43,7 +42,7 @@ Child pipelines work well with other GitLab CI/CD features:
 - Since the parent pipeline in `.gitlab-ci.yml` and the child pipeline run as normal
   pipelines, they can have their own behaviors and sequencing in relation to triggers.
 
-See the [`trigger:`](../yaml/index.md#trigger) keyword documentation for full details on how to
+See the [`trigger`](../yaml/index.md#trigger) keyword documentation for full details on how to
 include the child pipeline configuration.
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
@@ -85,7 +84,7 @@ microservice_a:
         file: '/path/to/child-pipeline.yml'
 ```
 
-The maximum number of entries that are accepted for `trigger:include:` is three.
+The maximum number of entries that are accepted for `trigger:include` is three.
 
 Similar to [multi-project pipelines](multi_project_pipelines.md#mirror-status-of-a-triggered-pipeline-in-the-trigger-job),
 we can set the parent pipeline to depend on the status of the child pipeline upon completion:
diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md
index 1b23727b142..3ff22a16900 100644
--- a/doc/ci/pipelines/pipeline_architectures.md
+++ b/doc/ci/pipelines/pipeline_architectures.md
@@ -211,7 +211,7 @@ trigger_b:
 ```
 
 Example child `a` pipeline configuration, located in `/a/.gitlab-ci.yml`, making
-use of the DAG `needs:` keyword:
+use of the DAG `needs` keyword:
 
 ```yaml
 stages:
@@ -240,7 +240,7 @@ deploy_a:
 ```
 
 Example child `b` pipeline configuration, located in `/b/.gitlab-ci.yml`, making
-use of the DAG `needs:` keyword:
+use of the DAG `needs` keyword:
 
 ```yaml
 stages:
diff --git a/doc/ci/pipelines/pipelines_for_merged_results.md b/doc/ci/pipelines/pipelines_for_merged_results.md
index 2acef9be557..718519faf48 100644
--- a/doc/ci/pipelines/pipelines_for_merged_results.md
+++ b/doc/ci/pipelines/pipelines_for_merged_results.md
@@ -10,6 +10,10 @@ last_update: 2019-07-03
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7380) in GitLab 11.10.
 
+INFO:
+Get these pipelines and more in GitLab Ultimate.
+[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-ci-cd-external-docs).
+
 When you submit a merge request, you are requesting to merge changes from a
 source branch into a target branch. By default, the CI pipeline runs jobs
 against the source branch.
diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md
index a8ecb5e0d74..cf470836e32 100644
--- a/doc/ci/pipelines/settings.md
+++ b/doc/ci/pipelines/settings.md
@@ -134,7 +134,7 @@ For example:
 - `my/path/.my-custom-file.yml@mygroup/another-project`
 - `my/path/.my-custom-file.yml@mygroup/another-project:refname`
 
-If the configuration file is in a separate project, you can more set more granular permissions. For example:
+If the configuration file is in a separate project, you can set more granular permissions. For example:
 
 - Create a public project to host the configuration file.
 - Give write permissions on the project only to users who are allowed to edit the file.
@@ -267,7 +267,7 @@ when merging a merge request would cause the project's test coverage to decline.
 
 Follow these steps to enable the `Coverage-Check` MR approval rule:
 
-1. Set up a [`coverage:`](../yaml/index.md#coverage) regular expression for all jobs you want to include in the overall coverage value.
+1. Set up a [`coverage`](../yaml/index.md#coverage) regular expression for all jobs you want to include in the overall coverage value.
 1. Go to your project and select **Settings > General**.
 1. Expand **Merge request approvals**.
 1. Select **Enable** next to the `Coverage-Check` approval rule.