Add latest changes from gitlab-org/gitlab@15-3-stable-eev15.3.0-rc42

4 files changed, 189 insertions, 21 deletions

diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md
index 379a4b3224a..61ef8bbfab7 100644
--- a/doc/ci/yaml/artifacts_reports.md
+++ b/doc/ci/yaml/artifacts_reports.md
@@ -329,3 +329,27 @@ GitLab can display the results of one or more reports in the merge request
 [terraform widget](../../user/infrastructure/iac/mr_integration.md#output-terraform-plan-information-into-a-merge-request).
 
 For more information, see [Output `terraform plan` information into a merge request](../../user/infrastructure/iac/mr_integration.md).
+
+## `artifacts:reports:cyclonedx`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360766) in GitLab 15.3
+
+This report is a Software Bill of Materials describing the components of a project
+following the [cyclonedx](https://cyclonedx.org/docs/1.4) protocol format.
+
+You can specify multiple cyclonedx reports per job. These can be either supplied
+as a list of filenames, a filename pattern, or both:
+
+- List of filenames: `cyclonedx: [gl-sbom-npm-npm.cdx.json, gl-sbom-bundler-gem.cdx.json]`.
+- A filename pattern: `cyclonedx: gl-sbom-*.json`.
+- Combination of both of the above: `cyclonedx: [gl-sbom-*.json, my-cyclonedx.json]`.
+
+Below is an example of a job exposing cyclonedx artifacts:
+
+```yaml
+artifacts:
+  reports:
+    cyclonedx:
+      - gl-sbom-npm-npm.cdx.json
+      - gl-sbom-bundler-gem.cdx.json
+```
diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md
index 838710834ba..5158f80ea64 100644
--- a/doc/ci/yaml/includes.md
+++ b/doc/ci/yaml/includes.md
@@ -289,10 +289,10 @@ smoke-test-job:
 
 In `include` sections in your `.gitlab-ci.yml` file, you can use:
 
-- [Project variables](../variables/index.md#add-a-cicd-variable-to-a-project)
-- [Group variables](../variables/index.md#add-a-cicd-variable-to-a-group)
-- [Instance variables](../variables/index.md#add-a-cicd-variable-to-an-instance)
-- Project [predefined variables](../variables/predefined_variables.md)
+- [Project variables](../variables/index.md#add-a-cicd-variable-to-a-project).
+- [Group variables](../variables/index.md#add-a-cicd-variable-to-a-group).
+- [Instance variables](../variables/index.md#add-a-cicd-variable-to-an-instance).
+- Project [predefined variables](../variables/predefined_variables.md).
 - In GitLab 14.2 and later, the `$CI_COMMIT_REF_NAME` [predefined variable](../variables/predefined_variables.md).
 
   When used in `include`, the `CI_COMMIT_REF_NAME` variable returns the full
@@ -322,7 +322,11 @@ include:
   file: '.compliance-gitlab-ci.yml'
 ```
 
-For an example of how you can include these predefined variables, and the variables' impact on CI/CD jobs,
+You cannot use variables defined in jobs, or in a global [`variables`](../yaml/index.md#variables)
+section which defines the default variables for all jobs. Includes are evaluated before jobs,
+so these variables cannot be used with `include`.
+
+For an example of how you can include predefined variables, and the variables' impact on CI/CD jobs,
 see this [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos).
 
 ## Use `rules` with `include`
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index 3bb2007d6e3..0b434e7013c 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -171,11 +171,11 @@ Use `include:local` instead of symbolic links.
 
 **Possible inputs**:
 
-- A full path relative to the root directory (`/`).
+A full path relative to the root directory (`/`):
+
 - The YAML file must have the extension `.yml` or `.yaml`.
 - You can [use `*` and `**` wildcards in the file path](includes.md#use-includelocal-with-wildcard-file-paths).
-
-CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file).
+- You can use [certain CI/CD variables](includes.md#use-variables-with-include).
 
 **Example of `include:local`**:
 
@@ -208,10 +208,10 @@ use `include:file`. You can use `include:file` in combination with `include:proj
 
 **Possible inputs**:
 
-- A full path, relative to the root directory (`/`). The YAML file must have the
-  extension `.yml` or `.yaml`.
+A full path, relative to the root directory (`/`):
 
-CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file).
+- The YAML file must have the extension `.yml` or `.yaml`.
+- You can use [certain CI/CD variables](includes.md#use-variables-with-include).
 
 **Example of `include:file`**:
 
@@ -268,10 +268,11 @@ Use `include:remote` with a full URL to include a file from a different location
 
 **Possible inputs**:
 
-- A public URL accessible by an HTTP/HTTPS `GET` request. Authentication with the
-  remote URL is not supported. The YAML file must have the extension `.yml` or `.yaml`.
+A public URL accessible by an HTTP/HTTPS `GET` request:
 
-CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file).
+- Authentication with the remote URL is not supported.
+- The YAML file must have the extension `.yml` or `.yaml`.
+- You can use [certain CI/CD variables](includes.md#use-variables-with-include).
 
 **Example of `include:remote`**:
 
@@ -296,9 +297,12 @@ Use `include:template` to include [`.gitlab-ci.yml` templates](https://gitlab.co
 
 **Possible inputs**:
 
-- [`.gitlab-ci.yml` templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates).
+A [CI/CD template](../examples/index.md#cicd-templates):
 
-CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file).
+- Templates are stored in [`lib/gitlab/ci/templates`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates).
+  Not all templates are designed to be used with `include:template`, so check template
+  comments before using one.
+- You can use [certain CI/CD variables](includes.md#use-variables-with-include).
 
 **Example of `include:template`**:
 
@@ -2136,7 +2140,7 @@ This example creates four paths of execution:
 
 - 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).
+    [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/reliability/-/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
@@ -2784,11 +2788,15 @@ which must be in the `$PATH`.
 If you use the [Docker executor](https://docs.gitlab.com/runner/executors/docker.html),
 you can use this image from the GitLab Container Registry: `registry.gitlab.com/gitlab-org/release-cli:latest`
 
+If you use the [Shell executor](https://docs.gitlab.com/runner/executors/shell.html) or similar,
+[install `release-cli`](../../user/project/releases/release_cli.md) on the server where the runner is registered.
+
 **Keyword type**: Job keyword. You can use it only as part of a job.
 
 **Possible inputs**: The `release` subkeys:
 
 - [`tag_name`](#releasetag_name)
+- [`tag_message`](#releasetag_message) (optional)
 - [`name`](#releasename) (optional)
 - [`description`](#releasedescription)
 - [`ref`](#releaseref) (optional)
@@ -2832,8 +2840,6 @@ This example creates a release:
 - The `release` section executes after the `script` keyword and before the `after_script`.
 - A release is created only if the job's main script succeeds.
 - If the release already exists, it is not updated and the job with the `release` keyword fails.
-- If you use the [Shell executor](https://docs.gitlab.com/runner/executors/shell.html) or similar,
-  [install `release-cli`](../../user/project/releases/release_cli.md) on the server where the runner is registered.
 
 **Related topics**:
 
@@ -2887,6 +2893,30 @@ job:
     - if: $CI_PIPELINE_SOURCE == "schedule"
 ```
 
+#### `release:tag_message`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363024) in GitLab 15.3. Supported by `release-cli` v0.12.0 or later.
+
+If the tag does not exist, the newly created tag is annotated with the message specifed by `tag_message`.
+If omitted, a lightweight tag is created.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**:
+
+- A text string.
+
+**Example of `release:tag_message`**:
+
+```yaml
+  release_job:
+    stage: release
+    release:
+      tag_name: $CI_COMMIT_TAG
+      description: 'Release description'
+      tag_message: 'Annotated tag message'
+```
+
 #### `release:name`
 
 The release name. If omitted, it is populated with the value of `release: tag_name`.
@@ -2965,7 +2995,7 @@ released_at: '2021-03-15T08:00:00Z'
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271454) in GitLab 13.12.
 
-Use `release:assets:links` to include [asset links](../../user/project/releases/index.md#release-assets) in the release.
+Use `release:assets:links` to include [asset links](../../user/project/releases/release_fields.md#release-assets) in the release.
 
 Requires `release-cli` version v0.4.0 or later.
 
@@ -3221,6 +3251,7 @@ branch or merge request pipelines.
 **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).
+- Alternatively, the array of file paths can be in [`rules:changes:paths`](#ruleschangespaths).
 
 **Example of `rules:changes`**:
 
@@ -3239,6 +3270,8 @@ docker build:
 - 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`).
+- [`rules:changes:paths`](#ruleschangespaths) is the same as `rules:changes` without
+  any subkeys.
 
 **Additional details**:
 
@@ -3250,6 +3283,74 @@ docker build:
 
 - [Jobs or pipelines can run unexpectedly when using `rules: changes`](../jobs/job_control.md#jobs-or-pipelines-run-unexpectedly-when-using-changes).
 
+##### `rules:changes:paths`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90171) in GitLab 15.2.
+
+Use `rules:changes` to specify that a job only be added to a pipeline when specific
+files are changed, and use `rules:changes:paths` to specify the files.
+
+`rules:changes:paths` is the same as using [`rules:changes`](#ruleschanges) without
+any subkeys. All additional details and related topics are the same.
+
+**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:paths`**:
+
+```yaml
+docker-build-1:
+  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        - Dockerfile
+
+docker-build-2:
+  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        paths:
+          - Dockerfile
+```
+
+In this example, both jobs have the same behavior.
+
+##### `rules:changes:compare_to`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293645) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `ci_rules_changes_compare`. Enabled by default.
+
+Use `rules:changes:compare_to` to specify which ref to compare against for changes to the files
+listed under [`rules:changes:paths`](#ruleschangespaths).
+
+**Keyword type**: Job keyword. You can use it only as part of a job, and it must be combined with `rules:changes:paths`.
+
+**Possible inputs**:
+
+- A branch name, like `main`, `branch1`, or `refs/heads/branch1`.
+- A tag name, like `tag1` or `refs/tags/tag1`.
+- A commit SHA, like `2fg31ga14b`.
+
+**Example of `rules:changes:compare_to`**:
+
+```yaml
+docker build:
+  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        paths:
+          - Dockerfile
+        compare_to: 'refs/heads/branch1'
+```
+
+In this example, the `docker build` job is only included when the `Dockerfile` has changed
+relative to `refs/heads/branch1` and the pipeline source is a merge request event.
+
 #### `rules:exists`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4.
@@ -3792,7 +3893,9 @@ Use `trigger` to start a downstream pipeline that is either:
 
 **Possible inputs**:
 
-- For multi-project pipelines, path to the downstream project.
+- For multi-project pipelines, path to the downstream project. CI/CD variables
+  [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file)
+  in GitLab 15.3 and later.
 - For child pipelines, path to the child pipeline CI/CD configuration file.
 
 **Example of `trigger` for multi-project pipeline**:
@@ -3830,6 +3933,8 @@ trigger_job:
   and [scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule)
   are not passed to downstream pipelines by default. Use [trigger:forward](#triggerforward)
   to forward these variables to downstream pipelines.
+- [Job-level persisted variables](../variables/where_variables_can_be_used.md#persisted-variables)
+  are not available in trigger jobs.
 
 **Related topics**:
 
@@ -3861,6 +3966,17 @@ trigger_job:
 In this example, jobs from subsequent stages wait for the triggered pipeline to
 successfully complete before starting.
 
+**Additional details**:
+
+- [Optional manual jobs](../jobs/job_control.md#types-of-manual-jobs) in the downstream pipeline
+  do not affect the status of the downstream pipeline or the upstream trigger job.
+  The downstream pipeline can complete successfully without running any optional manual jobs.
+- [Blocking manual jobs](../jobs/job_control.md#types-of-manual-jobs) in the downstream pipeline
+  must run before the trigger job is marked as successful or failed. The trigger job
+  shows **pending** (**{status_pending}**) if the downstream pipeline status is
+  **waiting for manual action** (**{status_manual}**) due to manual jobs. By default,
+  jobs in later stages do not start until the trigger job completes.
+
 #### `trigger:forward`
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213729) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `ci_trigger_forward_variables`. Disabled by default.
diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md
index 4bffcbca1cc..f1cdcf57e64 100644
--- a/doc/ci/yaml/script.md
+++ b/doc/ci/yaml/script.md
@@ -258,3 +258,27 @@ pages-job:
   script:
     - 'curl --header "PRIVATE-TOKEN: ${PRIVATE_TOKEN}" "https://gitlab.example.com/api/v4/projects"'
 ```
+
+### Job does not fail when using `&&` in a script
+
+If you use `&&` to combine two commands together in a single script line, the job
+might return as successful, even if one of the commands failed. For example:
+
+```yaml
+job-does-not-fail:
+  script:
+    - invalid-command xyz && invalid-command abc
+    - echo $?
+    - echo "The job should have failed already, but this is executed unexpectedly."
+```
+
+The `&&` operator returns an exit code of `0` even though the two commands failed,
+and the job continues to run. To force the script to exit when either command fails,
+enclose the entire line in parentheses:
+
+```yaml
+job-fails:
+  script:
+    - (invalid-command xyz && invalid-command abc)
+    - echo "The job failed already, and this is not executed."
+```