GitLab CI Syntax and Variables Summary

TLDR

• The GitLab CI configuration file is .gitlab-ci.yml. It is recommended to use rules instead of the legacy only/except for better flexibility.
• It is recommended to use the ${VARIABLE_NAME} syntax for variable references to ensure correct parsing when concatenated with surrounding text.
• workflow:rules can globally control whether a Pipeline executes. If all rules evaluate to when:never, the entire Pipeline will not be triggered.
• The needs keyword can break Stage order constraints, allowing a Job to execute immediately after its specified dependencies are completed.
• Using YAML anchors (& and *) allows for the creation of reusable Job templates, reducing redundant configuration.

Basic Structure and Stages

The core configuration file for GitLab CI is .gitlab-ci.yml. The execution order is defined via stages. Jobs within the same stage run in parallel and must all succeed before proceeding to the next stage.

stages:
  - build
  - test
  - deploy

Choosing Between Rules and Only/Except

When to encounter this issue: When you need to precisely control Job execution based on branches, tags, or trigger sources.

GitLab officially no longer recommends using only/except, recommending rules instead. rules supports more complex logical judgments, and rules are evaluated in order.

# Recommended approach
deploy-job:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - if: $CI_COMMIT_TAG
      when: always
    - when: never

Notes on Variable References

When to encounter this issue: When a variable name is adjacent to other characters, causing Shell parsing errors.

In GitLab CI, it is recommended to always use the ${VARIABLE_NAME} syntax to reference variables. This clearly defines the scope of the variable name and avoids parsing conflicts.

Workflow: Global Pipeline Control

workflow:rules is used to determine whether to create an entire Pipeline; this is different from Job-level rules.

TIP

If workflow:rules is not configured, GitLab uses default rules (all pushes and merge requests will trigger a pipeline). If rules are configured but all match when:never, the Pipeline will not execute at all.

Practical Example: Controlling based on commit messages

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /\[skip ci\]/
      when: never
    - if: $CI_COMMIT_TITLE =~ /\[run ci\]/
      when: always
    - when: on_success

Performance Optimization: Needs and Cache

• Needs: Allows a Job to execute immediately after its dependent specific Job completes, without waiting for the entire Stage to finish.
• Cache: Used to store files across Pipelines (e.g., node_modules/). It is recommended to use ${CI_COMMIT_REF_SLUG} as the key to isolate different branches.

Templated Configuration

Using YAML Anchors allows you to avoid defining the same configuration repeatedly:

.build_template: &build_definition
  stage: build
  script:
    - echo "Building..."

build_job1:
  <<: *build_definition
  script:
    - make build

Predefined Environment Variables Reference

GitLab provides a rich set of predefined variables. The following are the categories most frequently used by developers:

• Commit-related: CI_COMMIT_SHA (commit version), CI_COMMIT_REF_NAME (branch or tag name), CI_COMMIT_SHORT_SHA (short SHA).
• Project-related: CI_PROJECT_ID, CI_PROJECT_URL, CI_PROJECT_PATH.
• Job-related: CI_JOB_ID, CI_JOB_NAME, CI_JOB_URL.
• Merge Request-related: CI_MERGE_REQUEST_IID, CI_MERGE_REQUEST_SOURCE_BRANCH_NAME.

For a detailed list of variables, please refer to the official GitLab documentation.

Changelog

• 2025-04-07 Initial documentation created.