GitLab CI rules:changes not working: why jobs always run, or never do
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
changesrule matches. A job it adds always runs, and achangesrule withwhen: neveralways 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
changesadds 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. ifandchangesin one rule must both be true. A merge request job withif: $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
changeschecks. - 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
- GitLab docs — rules:changes
- GitLab docs — rules:changes:compare_to
- GitLab docs — Jobs or pipelines run unexpectedly when using changes
- GitLab docs — Skip jobs if the branch is empty
- GitLab source — the rules:changes clause (changes.rb)
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.