workflow:rules, Job rules, if Expressions, changes, exists, Pipeline Sources, and Conditional Execution: Concepts, Architecture, and Mental Model

1. The problem: “Why did this run?” has two different answers

After Chapters 01–07 you can identify the source SHA, compiled configuration, runner boundary, variables, and secret capability. Conditional execution adds a decision layer before job execution. A common debugging mistake is to look at a missing job and ask “which runner rejected it?” when the job was never added to the pipeline. An even earlier possibility is that workflow:rules prevented the pipeline itself from being created.

That distinction matters operationally. A missing pipeline has no job IDs or runner trace. An existing pipeline with an omitted job has a pipeline ID and a compiled rule decision, but there is still no job queue entry for the omitted job. A queued job has crossed both rule gates and belongs to the runner/executor layer. Treating all three as “CI did not run” destroys useful evidence.

2. Mental model: two gates before execution

Read the flow left to right. An event, API request, schedule, or downstream trigger establishes a pipeline source plus ref/SHA. GitLab loads and compiles the CI configuration. workflow:rules then decides whether this configuration should produce a pipeline for that context. Only if a pipeline exists do job-level rules decide whether each job enters the graph and with which conditional attributes. Stages/needs and runners operate afterward.

            flowchart TD
                A[Event / API / schedule] --> B[Pipeline source + ref + SHA]
                B --> C[Compile .gitlab-ci.yml + includes]
                C --> D{workflow:rules}
                D -->|no match / never| X[No pipeline]
                D -->|allowed| E[Pipeline record]
                E --> F{Each job rules list}
                F -->|no match / never| O[Job omitted]
                F -->|first matching include rule| G[Job graph: stage / needs / when]
                G --> H[Queue + runner + executor]
                H --> I[Logs / reports / artifacts / side effects]
          

3. Name the state before writing rules

4. Pipeline source is an input, not a guess

CI_PIPELINE_SOURCE is a pre-pipeline variable and should be the first discriminator when behavior differs by trigger class. The current primary documentation defines sources such as the following. The list is broader than “push versus merge request,” which is why broad catch-all rules are risky.

5. Gate one: workflow:rules controls pipeline existence

workflow:rules is evaluated before job rules. If no workflow rule allows the context, there is no pipeline, so a job-level rule cannot “bring the pipeline back.” Keep workflow policy small and legible: identify the pipeline classes your repository intentionally supports, reject known duplicates or untrusted contexts, then let jobs specialize inside the admitted classes.

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "push"'
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - when: never

This is an explicit allowlist with a duplicate-suppression rule before the ordinary push rule. It is not a universal template: downstream/API/trigger pipelines are intentionally rejected here. If your repository needs them, add those sources deliberately rather than replacing the last line with when: always.

6. Gate two: job rules uses first-match semantics

For a job, GitLab evaluates rules in order. The first matching rule determines inclusion/exclusion and conditional attributes; later rules are not consulted. If no rule matches, the job is omitted. Order therefore expresses precedence. Put narrow exceptions before broad cases and make the final behavior explicit.

unit_tests:
  stage: test
  script:
    - ./ci/run-unit-tests.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        paths:
          - src/**/*
          - tests/**/*
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

In a schedule the first rule excludes the job even if later conditions could have matched. In an MR the second rule requires both the source expression and a relevant diff. On a default-branch push the third rule includes the job. A feature-branch push that reaches no match omits the job.

7. if expressions: evaluate metadata, not shell code

rules:if is evaluated by GitLab during pipeline creation. It is not a shell command and cannot inspect files created by jobs. Current GitLab expressions support equality/inequality, null/empty checks, Boolean composition, and RE2 regular-expression matching. Treat user-provided pipeline values as untrusted data even though the expression evaluator is not a shell: a rule match can grant a privileged job access to protected runners, variables, deployments, or expensive compute.

release_candidate_checks:
  script: ./ci/check-candidate.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$/'

8. changes asks “what differs?” and the comparison base matters

rules:changes is diff-sensitive. In merge request pipelines GitLab compares with the target branch. In ordinary branch push pipelines it compares with the previous commit. For a new branch, and for pipeline types without an associated push event such as schedule/manual/tag contexts, an unqualified changes condition can evaluate true unexpectedly. Use an explicit source guard and, when you need deterministic behavior outside push/MR contexts, use compare_to.

docs_check:
  script: ./ci/check-docs.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        paths:
          - docs/**/*
          - mkdocs.yml
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'
      changes:
        compare_to: 'refs/heads/main'
        paths:
          - docs/**/*
          - mkdocs.yml

9. exists asks “is this capability in the repository?”

rules:exists checks paths in repository content for the evaluated project/ref. It is useful for capability detection such as “does this service contain a package.json?” It is not a runtime filesystem probe and cannot see an artifact generated by an earlier job because rules are resolved before jobs execute.

node_tests:
  script: npm test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      exists:
        - package.json

When exists is used with configuration includes, the lookup context can be the project/ref containing the include, not necessarily the project running the pipeline. That distinction becomes important in later reuse/component chapters.

10. Read-only inspection before changing anything

When conditional behavior surprises you, collect non-destructive evidence before editing YAML:

1. Record pipeline ID (if one exists), source, ref, and SHA from the pipeline UI/API.
2. Open CI Lint / merged configuration and confirm the configuration GitLab compiled for the revision.
3. List the jobs that actually exist in the pipeline. An omitted job has no job ID.
4. For changes, state the comparison context: MR target, prior push commit, or explicit compare_to.
5. For exists, state the project/ref whose repository tree is inspected.
6. Only after the job exists should you move to queue/runner/script evidence.

11. Mental-model summary

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-11. GitLab CI/CD rule semantics evolve; self-managed installations should confirm their deployed GitLab version before relying on newer syntax.

• workflow keyword — pipeline-creation rules, duplicate-pipeline avoidance, branch-to-MR switching, and current source examples.
• Specify when jobs run with rules — first-match evaluation, CI_PIPELINE_SOURCE values, expressions, schedules, changes, and duplicate-pipeline guidance.
• CI/CD YAML syntax reference — authoritative rules, rules:changes, compare_to, rules:exists, when, and workflow syntax.
• Predefined CI/CD variables — variable availability phases and safe source/ref/SHA metadata.
• Debugging CI/CD pipelines — current guidance for unexpected changes behavior and duplicate pipelines.
• Troubleshooting merge request pipelines — evidence and repair guidance for branch + MR duplicates.