Merge branch...

Merge branch '57287-documentation-for-handling-more-complex-only-merge_requests-scenarios-is-sparse' into 'master'

Docs for MR pipeline rule interactions

Closes #57287

See merge request gitlab-org/gitlab-ce!24929

doc/ci/merge_request_pipelines/index.md

@@ -56,6 +56,49 @@ The same tag is shown on the pipeline's details:
 
 ![Pipeline's details](img/pipeline_detail.png)
 
+## Excluding certain jobs
+
+The behavior of the `only: merge_requests` rule is such that _only_ jobs with
+that rule are run in the context of a merge request; no other jobs will be run.
+
+However, you may want to reverse this behaviour, having all of your jobs to run _except_
+for one or two. Consider the following pipeline, with jobs `A`, `B`, and `C`. If you want
+all pipelines to always run `A` and `B`, but only want `C` to run for a merge request,
+you can configure your `.gitlab-ci.yml` file as follows:
+
+``` yaml
+.only-default: &only-default
+  only:
+    - master
+    - merge_requests
+    - tags
+
+A:
+  <<: *only-default
+  script:
+    - ...
+
+B:
+  <<: *only-default
+  script:
+    - ...
+
+C:
+  script:
+    - ...
+  only:
+    - merge_requests
+```
+
+Since `A` and `B` are getting the `only:` rule to execute in all cases, they will
+always run. `C` specifies that it should only run for merge requests, so for any
+pipeline except a merge request pipeline, it will not run.
+
+As you can see, this will help you avoid a lot of boilerplate where you'd need
+to add that `only:` rule to all of your jobs in order to make them always run. You
+can use this for scenarios like having only pipelines with merge requests get a
+Review App set up, helping to save resources.
+
 ## Important notes about merge requests from forked projects
 
 Note that the current behavior is subject to change. In the usual contribution