Merge branch 'docs-skip-empty-branch-pipelines' into 'master'

Update rules for empty branches

See merge request gitlab-org/gitlab!37901

doc/ci/yaml/README.md

@@ -345,10 +345,10 @@ have [duplicate pipelines](#differences-between-rules-and-onlyexcept).
 Useful workflow rules clauses:
 
 | Clause                                                                     | Details                                                 |
-|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
+|----------------------------------------------------------------------------|---------------------------------------------------------|
 | `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'`                       | Allow or block merge request pipelines.                 |
 | `if: '$CI_PIPELINE_SOURCE == "push"'`                                      | Allow or block both branch pipelines and tag pipelines. |
-| `if: $CI_COMMIT_BEFORE_SHA == '0000000000000000000000000000000000000000'` | Allow or block pipeline creation when new branches are created or pushed with no commits. |
+| `if: '$CI_COMMIT_BEFORE_SHA == '0000000000000000000000000000000000000000'` | Allow or block pipeline creation when new branches are created or pushed with no commits. This will also skip tag and scheduled pipelines. See [common `rules:if` clauses](#common-if-clauses-for-rules) for examples on how to define these rules more strictly. |
 
 #### `workflow:rules` templates
 
@@ -1297,8 +1297,10 @@ Some details regarding the logic that determines the `when` for the job:
 - You can define `when` once per rule, or once at the job-level, which applies to
   all rules. You can't mix `when` at the job-level with `when` in rules.
 
+##### Common `if` clauses for `rules`
+
 For behavior similar to the [`only`/`except` keywords](#onlyexcept-basic), you can
-check the value of the `$CI_PIPELINE_SOURCE` variable.
+check the value of the `$CI_PIPELINE_SOURCE` variable:
 
 | Value                         | Description                                                                                                                                                                                                                                                                                                                                           |
 |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -1358,6 +1360,29 @@ Other commonly used variables for `if` clauses:
 - `if: '$CUSTOM_VARIABLE == "value1"'`: If the custom variable `CUSTOM_VARIABLE` is
   exactly `value1`.
 
+To avoid running pipelines when a branch is created without any changes,
+check the value of `$CI_COMMIT_BEFORE_SHA`. It has a value of
+`0000000000000000000000000000000000000000`:
+
+- In branches with no commits.
+- Tag pipelines and scheduled pipelines. You should define rules very
+  narrowly if you don't want to skip these.
+
+To skip pipelines on all empty branches, but also tags and schedules:
+
+```yaml
+rules:
+  - if: $CI_COMMIT_BEFORE_SHA == '0000000000000000000000000000000000000000'
+    when: never
+```
+
+To skip branch pipelines when the branch is empty:
+
+```yaml
+rules:
+  - if: $CI_COMMIT_BRANCH && $CI_COMMIT_BEFORE_SHA != '0000000000000000000000000000000000000000'
+```
+
 ##### `rules:changes`
 
 To determine if jobs should be added to a pipeline, `rules: changes` clauses check