GitLab CI "rules:if ... unknown variable" in CI

By Kaveh Alemi·Latchkey

GitLab rejected a rules:if clause because the expression is malformed or references a variable it does not recognize at config time. Rule expressions must compare variables with ==, !=, =~, or !~ and quote string literals.

What this error means

CI Lint reports "Invalid expression syntax" or the pipeline fails with a rules error naming the if clause. The job either never runs or the whole pipeline fails to create.

This GitLab CI configuration is invalid: jobs:deploy:rules:if invalid expression syntax

Common causes

A bare or misspelled variable reference

Writing if: CI_COMMIT_BRANCH == "main" without the $ sigil, or misspelling a predefined variable, makes the expression invalid.

Unquoted string literal or wrong operator

Comparing against an unquoted value, or using = instead of ==, produces invalid expression syntax.

How to fix it

Use the correct expression form

1. Prefix variables with $ and quote string literals.
2. Use ==, !=, =~, or !~ for comparisons.
3. Re-run CI Lint to confirm the expression parses.

deploy:
  script: ./deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Verify the variable exists at config time

Some variables are only set during a job, not when rules evaluate. Use predefined pipeline variables that are available at rules-evaluation time.

rules:
  - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

How to prevent it

• Always use the $VAR form inside rules:if.
• Quote string literals and use supported operators.
• Reference only variables defined when rules evaluate.

Frequently asked questions

Related guides

References

• GitHub Actions documentation