Right now every Orbit job runs on every push to every branch. That wastes minutes and, worse, it means a deploy job could run from a feature branch. Rules decide, per job and per pipeline, whether something runs. They are the difference between a pipeline that does the same thing everywhere and one that does the right thing in each situation.
How rules are evaluated
rules is a list of conditions. GitLab checks them top to bottom and stops at the first match. The matching rule decides how the job is added. If no rule matches, the job is not added at all.
deploy-staging:
stage: deploy
script: ./scripts/deploy.sh staging
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
This job exists only in pipelines for main. On a feature branch it is not skipped, it is simply absent from the pipeline graph.
Each rule can set what happens when it matches:
| Key | Effect |
|---|---|
when | on_success (default), manual, delayed, always or never |
allow_failure | Override the job’s setting for this case |
variables | Set variables only when this rule matches |
start_in | Delay for when: delayed |
needs | Change the job’s dependencies for this case |
rules:if — conditions on variables
if takes an expression on CI/CD variables:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
- if: $CI_COMMIT_BRANCH == "main" && $DEPLOY_ENABLED == "true"
- if: $CI_COMMIT_BRANCH != "main" || $FORCE_TESTS
| Operator | Meaning |
|---|---|
== / != | Equal / not equal (compare with a string or another variable) |
=~ / !~ | Matches / does not match a regular expression |
&& | And; the double pipe works as or, and parentheses group conditions |
$VAR alone | True if the variable is defined and not empty |
The four kinds of pipeline you will see
CI_PIPELINE_SOURCE tells you why a pipeline exists. These are the common cases:
| Situation | CI_PIPELINE_SOURCE | Useful variables |
|---|---|---|
| Push to a branch | push | CI_COMMIT_BRANCH |
| Push of a tag | push | CI_COMMIT_TAG |
| Merge request opened or updated | merge_request_event | CI_MERGE_REQUEST_IID, CI_MERGE_REQUEST_TARGET_BRANCH_NAME |
| Scheduled pipeline | schedule | Variables set on the schedule |
| “Run pipeline” button | web | Anything typed into the form |
| API call or trigger token | api / trigger | Variables sent in the request |
rules:changes — only when files changed
Skip the front-end tests when nobody touched the front end:
web-tests:
script: cd web && npm ci && npm test
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
changes:
- web/**/*
- package-lock.json
changes compares the files in the push or merge request with a reference. In merge request pipelines it compares against the target branch, which is what you want. In branch pipelines it compares with the previous push, which can miss changes on a brand new branch. Pin the comparison explicitly to be safe:
rules:
- changes:
paths: [web/**/*]
compare_to: refs/heads/main
Never use changes to skip required checks on main. If a merge commit is the only commit on main, change detection can be surprising. Run the full suite on the default branch and use changes to save time on merge requests.
rules:exists — only if a file is present
Run a job only in repositories that contain a given file. This shines in shared templates used by many projects:
docker-build:
rules:
- exists:
- Dockerfile
when: never — excluding cases
Put exclusions first, then the cases where the job should run:
e2e-tests:
rules:
- if: $CI_COMMIT_MESSAGE =~ /\[skip e2e\]/
when: never
- if: $CI_PIPELINE_SOURCE == "schedule"
when: never
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Manual and delayed jobs
deploy-production:
stage: deploy
script: ./scripts/deploy.sh production
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
allow_failure: false
warm-cache:
stage: deploy
script: ./scripts/warm-cache.sh
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: delayed
start_in: 10 minutes
A manual job inside rules defaults to allow_failure: false, so the pipeline shows as blocked until someone clicks it. That is usually what you want for a production gate: the pipeline is not “green” until production is done. Set allow_failure: true if the manual step is optional.
workflow:rules — rules for the whole pipeline
Job rules decide which jobs run. workflow:rules decides whether a pipeline is created at all. The classic problem it solves: push to a branch that has an open merge request and you get two pipelines, one for the push and one for the merge request, doing the same work twice.
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
when: never
- if: $CI_COMMIT_BRANCH
- if: $CI_COMMIT_TAG
- if: $CI_PIPELINE_SOURCE == "schedule"
Read it top to bottom:
- Merge request event? Create a merge request pipeline.
- A branch push while that branch has an open merge request? No pipeline, the MR pipeline covers it.
- Any other branch push? Branch pipeline.
- Tags and schedules? Yes.
GitLab ships this logic as a template too: include: - template: Workflows/MergeRequest-Pipelines.gitlab-ci.yml (merge request pipelines only) or Workflows/Branch-Pipelines.gitlab-ci.yml.
workflow can also give pipelines readable names, which makes the pipeline list much easier to scan:
workflow:
name: "$CI_PIPELINE_SOURCE: $CI_COMMIT_REF_NAME"
Cancel outdated pipelines
When a developer pushes three commits in a minute, the first two pipelines are useless. Mark jobs that are safe to stop as interruptible and tell GitLab to cancel them:
workflow:
auto_cancel:
on_new_commit: interruptible
default:
interruptible: true
deploy-production:
interruptible: false
script: ./scripts/deploy.sh production
Tests and builds are safe to interrupt. Deploys and database migrations are not; leave those interruptible: false so they always finish. Also check Settings → CI/CD → General pipelines → Auto-cancel redundant pipelines is enabled.
Avoid only and except
Old pipelines use only: and except::
deploy:
only:
- main
They still work but are no longer developed, cannot express many cases and cannot be combined with rules in the same job. Write all new configuration with rules.
The Orbit rules
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
when: never
- if: $CI_COMMIT_BRANCH
- if: $CI_COMMIT_TAG
auto_cancel:
on_new_commit: interruptible
.on-mr-and-main:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
.on-main-only:
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
unit-tests:
extends: [.node-job, .on-mr-and-main]
script: npm test
deploy-staging:
extends: .on-main-only
stage: deploy
script: ./scripts/deploy.sh staging
deploy-production:
stage: deploy
script: ./scripts/deploy.sh production
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
interruptible: false
extends accepts a list, so a job can inherit its setup from one template and its rules from another.
Exercise
A job has two rules: first “if: $CI_COMMIT_BRANCH == ‘main'” with when: manual, then “if: $CI_COMMIT_BRANCH” with no when. What happens in a pipeline for main?
Show answer
Answer: A. Rules are checked in order and evaluation stops at the first match. Order your rules from most specific to most general and put when: never exclusions first.
Exercise
You open a merge request and every push now creates two identical pipelines. What fixes it?
Show answer
Answer: C. One pipeline comes from the push and one from the merge request event. workflow:rules decide whether a pipeline is created at all, so they are the right place to drop the duplicate.
Key takeaways
- Rules are checked top to bottom; the first match wins; no match means the job is not added.
iftests variables,changestests modified files,existstests files in the repo.CI_PIPELINE_SOURCEtells you why the pipeline runs.workflow:rulesdecides whether a pipeline exists and prevents duplicates.interruptibleplusauto_cancelstop outdated pipelines; never interrupt a deploy.- Use
rulesfor all new configuration instead ofonlyandexcept.
FAQ
Why does my job not appear in the pipeline at all?
None of its rules matched. A job with rules is only added when a rule matches; there is no implicit “otherwise run”. Add a final catch-all rule such as - when: on_success if the job should run in every other case.
What is the difference between when: never and leaving the job out of rules?
Both result in no job. when: never lets you exclude specific cases before broader rules that would otherwise match.
Why does rules:changes run my job on every new branch?
The first push of a new branch has no previous push to compare with, so every file counts as changed. Use compare_to: refs/heads/main or rely on merge request pipelines, which compare with the target branch.
Can I trigger a pipeline that runs only some jobs?
Yes. Run it manually or through the API with a variable, for example ONLY_E2E=true, and add rules that check it. Many teams use this for scheduled nightly jobs.
Do protected branches affect rules?
Not directly, but they affect which variables and runners a pipeline gets. Combine if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH with a protected main so deploy jobs only run on code that went through review.