GitLab CI rules:changes not working: why jobs always run, or never do

By Melih Toksari, developer of MergeBell · Updated · 4 min read

Short answer

rules:changes adds a job only when the listed files changed, but GitLab can compare only when the pipeline comes from a push to an existing branch or from a merge request. For a new branch, a tag, a schedule, the New pipeline button, the API or a trigger token, there's nothing to compare, so it's always true and the job always runs; add compare_to, such as refs/heads/main, to compare with a branch instead, and a rule for main itself, where nothing then differs. A job that never runs usually has a path that doesn't match: docs and docs/ match no files, so use docs/**/*, and "*.md" matches only the root folder, so use "**/*.md". Branch pipelines compare with the branch before the push; merge request pipelines with everything the merge request changed.

You add rules:changes so a job runs only when certain files change, and then it runs on every pipeline, or never. Both come down to what GitLab compares the files against, and how it matches paths. Here’s how it works in GitLab 19.5.

docs-build:
  script: make docs
  rules:
    - changes:
        - docs/**/*

What GitLab compares against

Pipeline Files changes checks
Merge request Every file the merge request changes, compared with its target branch
Push to an existing branch Files changed by the push, from where the branch was before it
New branch’s first push None: always true
Tag, scheduled, New pipeline, API, trigger token None: always true
Any, with compare_to Files changed since the commit where the pipeline’s commit and that ref split

So:

  • A new branch always runs the job, because GitLab has nothing to compare its first push with.
  • A push that doesn’t touch the files skips the job, even if an earlier push did and that job failed. Merge request pipelines don’t have that gap: they check everything the merge request changes, on every push.
  • In scheduled and manual pipelines, every changes rule matches. A job it adds always runs, and a changes rule with when: never always skips its job. See scheduled pipelines.

The job always runs

Add compare_to to compare with a branch in every kind of pipeline:

docs-build:
  script: make docs
  rules:
    - changes:
        paths:
          - docs/**/*
        compare_to: refs/heads/main

On main itself nothing differs from refs/heads/main, so the job doesn’t run there, scheduled pipelines on main included. If it should, put a rule before it, such as - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH.

compare_to takes a branch, a tag or a commit SHA, and CI/CD variables since GitLab 17.2, such as refs/heads/$CI_DEFAULT_BRANCH. It can give unexpected results in merged results pipelines and in forks. With compare_to and **/*, a job skips branches that don’t change anything yet.

Two more reasons the job always runs:

  • Too many comparisons. Past 50,000 checks of changed files against patterns, GitLab assumes a match.
  • Another rule matches first. Rules are checked in order and the first match wins, so an earlier rule without changes adds the job anyway.

The job never runs

Usually the path doesn’t match. Paths are globs, matched from the repository root:

Pattern Matches
docs or docs/ Nothing: a directory name alone matches no files
docs/* Files directly in docs, not in its subfolders
docs/**/* Everything in docs and its subfolders
"*.md" Markdown files in the root folder only
"**/*.md" Markdown files anywhere, including the root
src/**/*.{js,ts} JavaScript and TypeScript files in src
./docs/**/* Nothing: paths can’t start with ./
  • Quote patterns that start with *, or the YAML is invalid.
  • Variables work in paths, but a trailing slash in the variable makes a double slash, like path/to/files//*, which doesn’t match.
  • if and changes in one rule must both be true. A merge request job with if: $CI_PIPELINE_SOURCE == "merge_request_event" never runs in a branch pipeline, whatever changed.
  • A section takes up to 50 patterns.

Skip a job when only docs changed

changes matches if any listed file changed. So this skips the job whenever a docs file changed, even alongside code:

rules:
  - changes:
      - docs/**/*
    when: never
  - when: on_success

It also skips the job in every pipeline with nothing to compare, such as a new branch’s first pipeline or a schedule. Instead, list the files the job needs, such as src/**/*. Since GitLab 19.2, changes: regexp: takes a Ruby regular expression, so a job can run when at least one changed file is outside docs/:

backend-tests:
  script: make test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        regexp: '\A(?!docs/).*'

regexp and paths can’t be in the same changes section. To skip a whole pipeline instead, see how to skip a GitLab CI pipeline.

Check what changed

  • In a merge request, the Changes tab lists the files changes checks.
  • For a push, compare the commits before and after it, such as git diff --name-only <before> <after>.
  • Duplicate pipelines, one for the branch and one for the merge request, each check different files. See GitLab merge request pipelines.

On your phone

MergeBell shows each pipeline’s jobs and their status, so a job that rules:changes left out, or one that ran when it shouldn’t have, is easy to spot, and Retry reruns a job on the free tier. Rules are checked when GitLab creates the pipeline, so a fix to .gitlab-ci.yml needs a new commit. More in how to retry a failed GitLab pipeline.

Frequently asked questions

Why does my GitLab job with rules:changes always run?

rules:changes is always true when GitLab has nothing to compare with: a new branch's first pipeline, tag pipelines, scheduled pipelines, pipelines from the New pipeline button, the API or a trigger token. Add compare_to under changes, such as compare_to: refs/heads/main with the files under paths, so GitLab compares with that branch instead; on main itself nothing then differs, so add a rule for it. More than 50,000 comparisons between changed files and patterns also count as a match.

Why does my GitLab job with rules:changes never run?

Usually the path doesn't match. Paths are matched as globs from the repository root: docs or docs/ match no files, docs/* matches only files directly in docs, and "*.md" only Markdown files at the root. Use docs/**/* and "**/*.md", don't start paths with ./, and quote patterns that start with *. Also check that the rule's if condition is true too: if and changes in one rule must both match.

What does GitLab compare rules:changes against?

In a merge request pipeline, every file the merge request changes compared with its target branch. In a branch pipeline, the files changed by the push, from where the branch was before it. With compare_to, the files changed since the commit where the pipeline's commit and that ref split. Without a push or a merge request there's nothing to compare, and changes is true.

How do I skip a GitLab job when only documentation changed?

Listing docs/**/* with when: never skips the job whenever any docs file changed, even alongside code, because changes matches if any listed file changed. Instead, list the code paths the job needs, or, from GitLab 19.2, use changes: regexp: '\A(?!docs/).*', which matches when at least one changed file is outside docs/.

How do I use rules:changes:compare_to in GitLab?

Put the files under changes: paths: and the ref to compare with under changes: compare_to:, such as refs/heads/main or $CI_DEFAULT_BRANCH. GitLab then compares the pipeline's commit with that ref in every kind of pipeline, including new branches and schedules. On that ref itself nothing differs, so the job doesn't run there unless an earlier rule, such as if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH, adds it. It can give unexpected results in merged results pipelines and in forks.

Sources

Checked against these pages on 12 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.

Do this from your phone with MergeBell

Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.

Get MergeBell for iPhoneGet MergeBell for Android

On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.