Add new section describing usage in exclusion scenario

1 files changed, 43 insertions, 0 deletions

diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md
index bf1e61442d4..33e39f8d71d 100644
--- a/doc/ci/merge_request_pipelines/index.md
+++ b/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)
 
+## Making all jobs run for your MR pipelines 
+
+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.
+
+This behavior may not be intuitive when you want 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 set things up like this to make that work:
+
+``` 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