GitLab CI Variable Not Expanding Inside rules:if

rules:if compares expanded variable values. If a variable is undefined, defined too late, or the expression quoting is wrong, the comparison silently evaluates false and the job is skipped (or always runs).

What this error means

A job with a rules:if guard never runs (or always runs) even though you expect the variable to match. There is no error, just unexpected skip or inclusion.

# Job never runs: ${DEPLOY_ENV} is undefined at evaluation time,
# so the comparison is false.
deploy:
  rules:
    - if: '${DEPLOY_ENV} == "production"'

Common causes

Variable is undefined at rule-evaluation time

rules:if is evaluated at pipeline creation. Variables set in script or job-level variables that are not available at creation expand to empty.

Wrong quoting of the expression

The whole if expression should be a single quoted string; mixing quotes can make the comparison literal.

Comparing against the raw token

Writing if: ${DEPLOY_ENV == "x"} instead of if: '${DEPLOY_ENV} == "x"' compares the wrong thing.

How to fix it

Define the variable at the right scope

Set the variable in the project/group CI settings or top-level variables so it exists at pipeline creation.

variables:
  DEPLOY_ENV: "production"

deploy:
  rules:
    - if: '${DEPLOY_ENV} == "production"'

Quote the expression correctly

1. Wrap the entire if value in single quotes.
2. Reference variables with ${VAR} and compare to a double-quoted literal.
3. Re-test in the Pipeline Editor Validate tab with the variable set.

How to prevent it

• Define rule-gating variables at project/group level so they exist at creation.
• Always single-quote rules:if expressions.
• Validate rule outcomes in the editor with realistic variable values.

Related guides