Merge branch 'mc/documentation/rules-flattening' into 'master'

Document usage of !references in rules

See merge request gitlab-org/gitlab!68283

doc/ci/jobs/job_control.md

@@ -290,6 +290,35 @@ You can use the `$` character for both variables and paths. For example, if the
 `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the
 `$` is interpreted as being part of a path.
 
+## Reuse rules in different jobs
+
+> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) GitLab 14.3.
+
+Use [`!reference` tags](../yaml/index.md#reference-tags) to reuse rules in different
+jobs. You can combine `!reference` rules with regular job-defined rules:
+
+```yaml
+.default_rules:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+      when: never
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+job1:
+  rules:
+    - !reference [.default_rules, rules]
+  script:
+    - echo "This job runs for the default branch, but not schedules."
+
+job2:
+  rules:
+    - !reference [.default_rules, rules]
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - echo "This job runs for the default branch, but not schedules."
+    - echo "It also runs for merge requests."
+```
+
 ## Specify when jobs run with `only` and `except`
 
 You can use [`only`](../yaml/index.md#only--except) and [`except`](../yaml/index.md#only--except)

doc/ci/yaml/index.md

@@ -1141,6 +1141,9 @@ 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](#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:
@@ -4765,6 +4768,7 @@ into templates.
 ### `!reference` tags
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) in GitLab 13.9.
+> - `rules` keyword support [introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) GitLab 14.3.
 
 Use the `!reference` custom YAML tag to select keyword configuration from other job
 sections and reuse it in the current section. Unlike [YAML anchors](#anchors), you can