How do you express "only run this when..." in a pipeline file, without it turning into a mess?

The mental model that fixes most tangles: conditions decide whether a job exists in the pipeline, not what it does at run time. They are evaluated once, when the pipeline is created.

That distinction matters because it separates the two tools people mix:

• Pipeline rules — evaluated up front, decide inclusion. Use these for branch, tag, event type, changed paths.
• Shell conditionals inside a script — evaluated during the run, decide behaviour. Use these only for things not knowable in advance.

Mixing them is where the mess comes from. A job that always exists and then decides inside the script whether to do anything shows up as a green job that did nothing, which is why you cannot tell what ran.

Rule of thumb: if the answer is knowable when the pipeline starts, put it in the rules. Then the pipeline graph itself tells you what will happen, and you can read it instead of watching it.

On testing, because you said you find out by watching — you do not have to.

Most CI systems have a way to see what a pipeline would contain before running it: a lint or preview endpoint that takes your configuration and a set of conditions and reports which jobs would be created. Running that against a few scenarios — main branch, tag, merge request, docs-only change — takes minutes and catches exactly the surprises you are describing.

Where that is not available, the cheap version is a scratch branch and a no-op pipeline. Still faster than discovering it on a release.

The three things that keep it readable, in order of impact:

First match wins, so order matters. Most rule systems evaluate top to bottom and stop. Write the exclusions first and the general case last. Half of "it ran when I did not expect" is a broad rule sitting above a narrow one.

Extract shared conditions. Both major CI ecosystems have a way to define a rule set once and reuse it — anchors, templates, extends. Three jobs sharing "only on the default branch" should reference one definition, so changing the policy is one edit rather than three and a missed one.

Name the intent. A comment above each rule saying what it is for in English. Conditions accumulate over years and nobody remembers which incident produced the third clause.

Also: be explicit about merge request pipelines. The single most common source of surprise is a job running twice, once for the branch and once for the merge request, because the rules did not say which. Deciding that deliberately removes a whole category of confusion.

One warning about the changed-paths condition specifically, since it is usually in these tangles: it interacts badly with required checks.

A job skipped because no relevant files changed may never report a status, and a merge waiting on that status waits forever. Most platforms have a setting for treating a skipped required job as passed, and it is worth configuring at the same time as you add the path rule rather than discovering it later.