Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท GitLab CI/CD Pipelines

Variables and Rules

Use GitLab CI/CD variables (predefined, custom, masked, protected, file type) and the rules keyword with if, changes and exists to decide when jobs run.

Two features turn a fixed pipeline into a smart one. Variables carry information into your jobs: the branch name, the commit hash, a deployment URL, a secret. Rules decide whether a job runs at all, using that information. Together they let one .gitlab-ci.yml file behave differently for merge requests, the default branch, tags and schedules.

Predefined variables

Before your job starts, GitLab sets dozens of variables describing the context. Reference them with a dollar sign in scripts ($CI_COMMIT_SHA) and in rules. The ones you will use most:

Variable Meaning
CI_COMMIT_BRANCH Branch name (not set in merge request or tag pipelines)
CI_COMMIT_TAG Tag name, only in tag pipelines
CI_COMMIT_SHA / CI_COMMIT_SHORT_SHA Full or short commit hash
CI_COMMIT_REF_SLUG Branch or tag name made safe for URLs and DNS
CI_DEFAULT_BRANCH Name of the default branch, such as main
CI_PIPELINE_SOURCE What started the pipeline (push, merge_request_event, schedule, ...)
CI_MERGE_REQUEST_IID The ! number, only in merge request pipelines
CI_PROJECT_DIR Directory where the repository is checked out
CI_PROJECT_PATH group/project
CI_JOB_NAME, CI_JOB_ID, CI_PIPELINE_ID Identifiers
CI_REGISTRY_IMAGE Address of the project's container registry
CI_JOB_TOKEN Short-lived token for API and registry access

The easiest way to see exactly what a job receives is to print them while debugging (and be careful not to print secrets):

YAML
show-context:
  script:
    - echo "branch=$CI_COMMIT_BRANCH source=$CI_PIPELINE_SOURCE sha=$CI_COMMIT_SHORT_SHA"
    - env | grep '^CI_' | sort

Your own variables

Define variables in three places:

  1. In .gitlab-ci.yml with variables:, globally or per job. These are visible to everyone who can read the file, so only use them for non-secret values.
  2. In project or group settings, under Settings, then CI/CD, then Variables. These are the right place for secrets and values that differ between environments.
  3. At run time, when you press New pipeline in the web UI or call the API.
YAML
variables:
  NODE_ENV: "test"
  GREETING: "hello"

print:
  variables:
    GREETING: "hello from the job"   # job-level value wins
  script:
    - echo "$GREETING and $NODE_ENV"

When the same name is set in several places, the more specific one wins: roughly, a job's variables override pipeline-level ones, and pipeline variables passed at run time override project settings. Group variables are overridden by project variables. (The full precedence list in the documentation has more levels; check it when debugging.)

Protecting secret values

Variables set in the UI have options:

  • Masked: the value is replaced by [MASKED] in job logs. The value must meet formatting rules (no spaces, minimum length), and masking is a safeguard, not a guarantee, because a script can still transform and print it.
  • Protected: the variable is passed only to pipelines running on protected branches or tags. A deploy key kept this way cannot be read from an arbitrary feature branch.
  • Hidden (newer versions): the value is masked and cannot be revealed in the settings page afterwards.
  • Type: Variable (an environment variable) or File: GitLab writes the value to a temporary file and sets the variable to its path, which suits certificates and kubeconfigs.
  • Environment scope (paid tiers): limit a variable to a named environment such as production.

Never commit secrets to the repository. Remember the protected branches lesson: it is the protection of the branch that makes protected variables safe.

Rules: deciding if a job runs

The rules keyword is a list of conditions. GitLab checks them in order, and the first matching rule wins. Each rule can set when (on_success, manual, never, ...) and extra attributes such as variables. If no rule matches, the job is not added to the pipeline.

YAML
deploy-staging:
  stage: deploy
  script: ./deploy.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - when: never        # everything else: do not run

Three kinds of condition:

  • if evaluates an expression over variables: ==, !=, =~ and !~ (regular expression, written between slashes), combined with &&, || and parentheses.
  • changes matches when certain files changed: changes: [src/**/*, package.json].
  • exists matches when files exist in the repository.
YAML
build-docs:
  script: make docs
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - docs/**/*
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
      when: always

The changes condition behaves best in merge request pipelines, where GitLab compares against the target branch. In plain branch pipelines on a new branch it can match unexpectedly, so test it.

A mini rules engine

The stand-in below evaluates simple if expressions (==, !=, =~, &&, ||) against a dictionary of variables and applies the first-match logic. It teaches how GitLab thinks; the real expression language has more features.

Python Stand-in: evaluate rules like GitLab does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Try adding a rule or reordering them to see why order matters: the never rule at the top shuts out merge request pipelines before later rules get a look.

Workflow rules: controlling the whole pipeline

workflow:rules uses the same syntax at the top of the file to decide whether a pipeline is created at all. It is how you avoid duplicate pipelines (one for the branch push and another for the merge request):

YAML
workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH

This says: run merge request pipelines; skip branch pipelines for a branch that already has an open MR; otherwise run branch pipelines. The older only and except keywords still work but are deprecated in favor of rules; do not mix rules with them in one job.

Variables inside rules and expansion

Variables defined under variables: can be used in rules:if, and a rule can set variables for the job:

YAML
deploy:
  script: ./deploy.sh $TARGET
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      variables:
        TARGET: production
    - if: $CI_COMMIT_BRANCH
      variables:
        TARGET: review

Inside scripts, variable expansion is done by the shell: $VAR or ${VAR}. Quote it ("$VAR") so spaces survive. A literal dollar sign in a variables value should be written $$.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which variable tells you what started the pipeline?

    CI_PIPELINE_SOURCE holds values such as push, merge_request_event, schedule or web.
  2. 2. A deploy key must never be available to feature branches. Which setting helps?

    Protected variables are passed only to pipelines on protected branches and tags.
  3. 3. In a rules list, what happens when two rules match?

    Rules are evaluated in order and the first match decides when (and whether) the job runs.
  4. 4. What is workflow:rules for?

    workflow:rules control pipeline creation, which is how you avoid duplicate branch and merge request pipelines.

Summary

  • Predefined CI_* variables describe the commit, branch, pipeline and job.
  • Custom variables live in the YAML (non-secret) or in settings (secrets); mask and protect secrets.
  • rules (with if, changes, exists and when) decide whether a job runs; the first match wins.
  • workflow:rules controls whether a pipeline is created at all.
  • Prefer rules over the deprecated only and except.

Next: Artifacts and Cache