Skip to main content

Rules

Rules control whether a workflow runs based on conditions you define. Use workflow.rules to gate pipeline execution on branch names, environment flags, or other criteria.

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Current status​

Loom validates rule structure today and is building toward full expression evaluation.

CapabilityStatus
Schema shape validated (workflow.rules as a sequence of {if: ...})Enforced
if must be a non-empty stringEnforced
Only if key allowed per rule entry (no when, changes)Enforced
Expression evaluation at runtimePlanned
Variable availability during rule evaluationPlanned
Job-level rulesPlanned

What this means in practice: you can write workflow.rules today and loom check will validate the structure. The expressions are not yet evaluated at runtime to gate execution. Use rules for forward-compatible structure, and handle gating logic in job scripts or your surrounding CI system until evaluation is implemented.

Syntax​

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Shape rules​

  • workflow is a mapping that only allows the key rules.
  • workflow.rules is a YAML sequence.
  • Each entry is a mapping with a single required key: if.
  • if must be a non-empty string.

Any other keys under workflow or within a rule entry produce a schema error.

Validation​

loom check

If the structure is invalid, loom check reports errors like:

ErrorFix
remove unknown key; workflow only allows key rulesRemove extra keys from the workflow mapping
set workflow.rules to a sequence of {if: ...} entriesChange rules to a YAML sequence
set workflow.rules[].if to a non-empty string conditionProvide a non-empty condition string
remove unknown key; workflow rules only allow key ifRemove extra keys (like when) from rule entries
add required key if to workflow ruleAdd an if key to the rule mapping

Example patterns​

These examples show common rule intents. The expression syntax follows $VARIABLE operator "value" conventions familiar from other CI platforms. Exact operator support and evaluation semantics will be documented when expression evaluation ships.

Run only on main​

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Run on everything except main​

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH != "main"

Run only when a branch is known​

Avoid detached HEAD scenarios where CI_COMMIT_BRANCH is empty:

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH != ""

Multiple conditions​

Each rule is evaluated independently. If any rule matches, the workflow runs:

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_BRANCH == "develop"

Variables in rules​

Rules reference variables using $VARIABLE_NAME syntax. Loom provides a set of predefined variables to every job, including CI_COMMIT_BRANCH, CI_COMMIT_SHA, and others.

Since expression evaluation is not yet implemented, the best way to verify variable availability today is to print variables in a job script:

debug:
  stage: ci
  target: linux
  script:
    - env | grep -E '^CI_|^LOOM_' | sort

Once you confirm a variable is available, you can reference it in a rule if expression. The rule will take effect when expression evaluation is implemented.

What to do today​

If you need conditional execution right now:

  1. Write rules for forward compatibility — add workflow.rules with the conditions you want. They will be enforced once evaluation ships.
  2. Gate in job scripts — use shell conditionals in script for immediate effect:
check:
  stage: ci
  target: linux
  script:
    - |
      if [ "$CI_COMMIT_BRANCH" != "main" ]; then
        echo "Skipping: not on main"
        exit 0
      fi
    - pnpm run check
  1. Gate in your outer CI — if Loom runs inside GitLab CI or GitHub Actions, use that platform's rule system to control when loom run is invoked.

Planned​

| Feature | Description | | ---------------------- | ------------------------------------------------------------------------- | --- | ------------------------------------ | | Expression language | Documented operators (==, !=, =~, &&, | |) with defined evaluation semantics | | Variable set for rules | Explicitly specified which variables are available during rule evaluation | | Rule actions | when key for allow/deny/manual semantics | | Job-level rules | Conditional execution per job, not just per workflow | | changes condition | Gate on file changes (similar to only/except patterns) |

Next steps​