Lesson 06 intermediate

Pipeline Rules

Decide which jobs run and when with rules:if, rules:changes and rules:exists, branch, tag, merge request and schedule pipelines, workflow:rules to avoid duplicate pipelines, manual and delayed jobs, interruptible jobs and auto-cancel, and why only/except is legacy.

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:

KeyEffect
whenon_success (default), manual, delayed, always or never
allow_failureOverride the job’s setting for this case
variablesSet variables only when this rule matches
start_inDelay for when: delayed
needsChange 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
OperatorMeaning
== / !=Equal / not equal (compare with a string or another variable)
=~ / !~Matches / does not match a regular expression
&⩓ the double pipe works as or, and parentheses group conditions
$VAR aloneTrue 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:

SituationCI_PIPELINE_SOURCEUseful variables
Push to a branchpushCI_COMMIT_BRANCH
Push of a tagpushCI_COMMIT_TAG
Merge request opened or updatedmerge_request_eventCI_MERGE_REQUEST_IID, CI_MERGE_REQUEST_TARGET_BRANCH_NAME
Scheduled pipelinescheduleVariables set on the schedule
“Run pipeline” buttonwebAnything typed into the form
API call or trigger tokenapi / triggerVariables 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:

  1. Merge request event? Create a merge request pipeline.
  2. A branch push while that branch has an open merge request? No pipeline, the MR pipeline covers it.
  3. Any other branch push? Branch pipeline.
  4. 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?

  1. The job is added as a manual job, because the first matching rule wins
  2. The job runs automatically, because the second rule also matches
  3. The job runs twice
  4. The job is not added
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?

  1. Add interruptible: true to every job
  2. Add rules:changes to every job
  3. Use workflow:rules that skip branch pipelines when the branch has an open merge request
  4. Delete the branch and push again
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.
  • if tests variables, changes tests modified files, exists tests files in the repo.
  • CI_PIPELINE_SOURCE tells you why the pipeline runs.
  • workflow:rules decides whether a pipeline exists and prevents duplicates.
  • interruptible plus auto_cancel stop outdated pipelines; never interrupt a deploy.
  • Use rules for all new configuration instead of only and except.

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.

↑ ↓ navigate Enter open Esc close