rules, workflow, Pipeline Sources, Changes, Conditions, and Dynamic Pipeline Creation: Configuration, Design Choices, and Tradeoffs

1. Design principle: place policy at the correct creation layer

Rule design is easier when the policy sentence has a clear subject. “No pipeline should exist for draft MRs” belongs at workflow:rules. “Run docs validation only when docs change” belongs on the docs job. Using a job rule to imitate whole-pipeline suppression leaves an empty or misleading pipeline; using workflow to suppress a pipeline just because one expensive job is irrelevant can remove useful fast feedback.

2. Workflow suppression versus per-job exclusion

3. rules:changes: efficient when the comparison is well-defined

Path filtering can save substantial compute in monorepos, but only when the comparison base matches the event. MR pipelines naturally compare with the target branch; branch pipelines compare with the previous commit. New branches and sources without a push require extra care. If a scheduled pipeline should run tests based on the current branch versus main, use compare_to explicitly rather than assuming the last push supplies a baseline.

backend_tests:
  script: ./test-backend.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - backend/**/*
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      changes:
        paths:
          - backend/**/*
        compare_to: 'refs/heads/main' 

4. Explicit positive rules versus broad catch-all fallbacks

An explicit allow-list makes newly introduced pipeline sources default to “not included” until reviewed. A final when: always is convenient but broad: it may include the job in scheduled, API, trigger, parent, policy-driven, or future pipeline sources you never intended.

5. Rule order is part of policy, not formatting

Because the first match wins, putting a broad branch rule above a special default-branch rule can make the special case unreachable. Review rules like firewall policy: from specific deny/override cases to intended general cases, with comments where order is security-significant.

# Wrong for a special default-branch manual gate:
rules:
  - if: '$CI_COMMIT_BRANCH'                  # catches main first
  - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    when: manual

# Better:
rules:
  - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    when: manual
  - if: '$CI_COMMIT_BRANCH' 

6. Prefer source identity over variable side effects

Do not use presence of a loosely related variable as a proxy for pipeline type if CI_PIPELINE_SOURCE expresses the intent directly. Source-specific variables then refine the case. This makes the configuration more compatible with web/API/schedule/child contexts and easier to diagnose from pipeline metadata.

7. Static configuration versus dynamic child pipelines

Static YAML is easier to review, lint, cache mentally, and audit. Dynamic child configuration can be valuable when the job graph itself is data-dependent—for example, generating component-specific pipelines in a large monorepo. But it creates another compiler step: generator inputs → generated YAML artifact → GitLab parser → child jobs.

8. Dynamic configuration is a code-generation trust boundary

If a generator reads untrusted branch content and emits YAML that can request privileged runners, protected environments, or secret-consuming jobs, the generator has become a policy compiler. Constrain the inputs, validate the generated file, use least-privilege runners/variables, and keep target-project privileged resources inaccessible to untrusted fork pipelines.

9. Offering, tier, and version boundaries

• Free path: all mandatory rule/workflow/change/existence examples and parent-child/dynamic child concepts are available on Free across GitLab.com, Self-Managed, and Dedicated.
• Runner compute: feature availability does not guarantee free hosted execution capacity; use CI Lint and no-runner reasoning when needed.
• GitLab 18.2+: directory paths are supported by rules:exists. Use file paths for older installations.
• GitLab 19.2: rules:changes:regexp is new. This chapter uses established glob/path behavior so older supported installations can follow the mandatory path.
• Self-Managed: verify instance version before adopting newer rule syntax or relying on SaaS-current behavior.

10. Worked decision table: monorepo delivery policy

Scenario: a monorepo has fast linting, backend tests, frontend tests, and a nightly full test. Which control belongs where?

11. Maintainability, reliability, performance, and cost

Every extra rule branch expands the state space you must test. Prefer small source matrices, centralize whole-pipeline decisions, and keep job-specific conditions local. Path filters can save compute but become a correctness risk when comparison semantics are misunderstood. Dynamic children can reduce monorepo fan-out but add artifact and parsing latency. Optimize only after the deterministic state model is testable.

Knowledge check

Summary

Good rule architecture is intentionally boring: a small pipeline-source contract at workflow level, local job predicates for job-specific work, explicit comparison semantics, minimal fallbacks, and dynamic configuration only when it solves a real topology problem. This reduces both runner waste and policy ambiguity.

Official references

• GitLab Docs — workflow keyword
• GitLab Docs — Specify when jobs run with rules
• GitLab Docs — CI/CD YAML syntax reference
• GitLab Docs — Predefined CI/CD variables
• GitLab Docs — Where variables can be used
• GitLab Docs — Merge request pipelines
• GitLab Docs — Downstream pipelines
• GitLab Docs — Pipeline editor
• GitLab Docs — CI Lint
• GitLab Docs — CI/CD pipelines
• GitLab Docs — Pipelines API
• GitLab Docs — Use CI/CD configuration from other files