Commit e6fcf2b6 authored by Marcel Amirault's avatar Marcel Amirault Committed by Evan Read

Update rules for empty branches

Add details on how to skip pipelines when a
branch is empty, and crosslink between workflow
and regular rules. Also expands rules examples into
a new linkable section
parent 313b826d
...@@ -345,10 +345,10 @@ have [duplicate pipelines](#differences-between-rules-and-onlyexcept). ...@@ -345,10 +345,10 @@ have [duplicate pipelines](#differences-between-rules-and-onlyexcept).
Useful workflow rules clauses: Useful workflow rules clauses:
| Clause | Details | | Clause | Details |
|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| |----------------------------------------------------------------------------|---------------------------------------------------------|
| `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'` | Allow or block merge request pipelines. | | `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_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 #### `workflow:rules` templates
...@@ -1297,8 +1297,10 @@ Some details regarding the logic that determines the `when` for the job: ...@@ -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 - 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. 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 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 | | Value | Description |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
...@@ -1358,6 +1360,29 @@ Other commonly used variables for `if` clauses: ...@@ -1358,6 +1360,29 @@ Other commonly used variables for `if` clauses:
- `if: '$CUSTOM_VARIABLE == "value1"'`: If the custom variable `CUSTOM_VARIABLE` is - `if: '$CUSTOM_VARIABLE == "value1"'`: If the custom variable `CUSTOM_VARIABLE` is
exactly `value1`. 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` ##### `rules:changes`
To determine if jobs should be added to a pipeline, `rules: changes` clauses check To determine if jobs should be added to a pipeline, `rules: changes` clauses check
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment