GitLab CI/CD: Exploring Pipeline Variables with Practical Examples

Variables are a fundamental component of any CI/CD pipeline, allowing users and developers to customize pipeline execution dynamically rather than relying solely on hardcoded values. DevOps engineers are responsible for designing flexible pipelines that cater to multiple scenarios and stakeholders (such as developer and operations teams) through configurable pipeline options.

1. Why Do We Need Pipeline Variables?

• Avoid Hardcoding: Hardcoded pipelines lack flexibility. Variables enable dynamic behavior across different environments and runs.
• User Customization: They empower users (developers, QA, and operations teams) to supply custom inputs at runtime when triggering a pipeline manually.
• Multi-Scenario Support: A single pipeline definition can handle different operational paths (e.g., running tests, selecting deployment targets) based on variable inputs.

2. Core Mental Model: Bash Variables in CI/CD

Conceptually, GitLab CI/CD variables behave similarly to shell/bash variables.

• Definition: Key-value pairs defined at the global or job level.
• Reference: Accessed within scripts and commands using the standard dollar sign prefix ($VARIABLE_NAME).

3. Global Variables (Static vs. Interactive)

Global variables are defined at the very top of the .gitlab-ci.yml file, making them available across all stages and jobs.

A. Static Global Variables (Fixed Values)

If you define a global variable with a simple key-value pair, its value is fixed throughout the pipeline execution and cannot be modified interactively by a user at runtime.

Pipeline Configuration (Naive Approach):

variables:
  BUILD_RUN: "yes"

stages:
  - build
  - test
  - deploy

my_build_job:
  stage: build
  script:
    - echo "Build run status: $BUILD_RUN"

my_test_job:
  stage: test
  script:
    - echo "Build run status in test: $BUILD_RUN"

B. Interactive Global Variables (User-Configurable)

To expose variables in the GitLab UI when a user manually runs a pipeline, you must define them using structured attributes: value (default value), description, and optionally restrict inputs.

Pipeline Configuration (Configurable Approach):

variables:
  BUILD_RUN: "yes"  # Fixed global variable
  IS_TEST_RUN:
    value: "true"
    description: "Specify whether to execute the test suite (true/false)"

stages:
  - build
  - test

build_job:
  stage: build
  script:
    - echo "Build run: $BUILD_RUN"
    - echo "Test run flag: $IS_TEST_RUN"

test_job:
  stage: test
  script:
    - echo "Test run flag in test stage: $IS_TEST_RUN"

4. Step-by-Step Pipeline Execution Flow with User Inputs

When you define interactive variables with descriptions, GitLab renders a form in the UI when clicking Run Pipeline.

5. Dropdown Menu Variables for Restricted Inputs

Sometimes you want to restrict user input to a predefined list of valid options rather than allowing arbitrary text. GitLab allows you to configure dropdown menus for variables using the options keyword.

Pipeline Configuration with Dropdown Options:

variables:
  DEPLOY_TYPE:
    value: "non-prod"
    options:
      - "non-prod"
      - "prod"
      - "pre-prod"
    description: "Select the target deployment environment"

stages:
  - deploy

deploy_job:
  stage: deploy
  script:
    - echo "Deploying to environment: $DEPLOY_TYPE"

Note: The default value specified in a dropdown variable must be included within the defined options list. When a user runs the pipeline via the UI, a dropdown select box appears, preventing arbitrary invalid inputs.

6. Job-Specific Variables (Local Scope)

Unlike global variables, job-specific variables are defined inside an individual job block.

Characteristics of Job-Specific Variables:

• Restricted Scope: They are only accessible within the specific job where they are defined. They cannot be accessed by other jobs in subsequent or parallel stages.
• No Runtime UI Prompt: Users cannot modify job-specific variables from the GitLab UI run pipeline screen.

Pipeline Configuration with Job-Specific Variables:

stages:
  - build
  - test

my_build_job:
  stage: build
  variables:
    IS_MAVEN_BUILD: "yes"
    MAVEN_OPTS: "-Xmx512m"
  script:
    - echo "Running Maven build: $IS_MAVEN_BUILD with options $MAVEN_OPTS"

my_test_job:
  stage: test
  script:
    - echo "Attempting to access job-specific variable: $IS_MAVEN_BUILD"
    # Result: $IS_MAVEN_BUILD will be empty/undefined here because it is out of scope.

7. Comparative Synthesis of Variable Types

8. Real-World Pitfalls & Debugging Mindset

• Variable Scope Confusion: If a job outputs an empty string when referencing a variable, verify whether the variable was defined globally or inside a separate job. Job-specific variables do not leak into other jobs.
• Dropdown Validation Errors: Ensure that the default value of a dropdown variable exactly matches one of the strings specified in the options array; otherwise, pipeline configuration validation may fail.
• Typo in Dollar Sign Prefix ($): Always prefix variable names with $ when referencing them in script commands (e.g., $BUILD_RUN). Omitting the $ treats the variable name as literal text.

Summary and Key Takeaways

• Pipeline Customization: Variables transform hardcoded pipelines into flexible, parameterized workflows suitable for development, staging, and production teams.
• Global vs. Job Scope: Global variables span the entire pipeline execution, whereas job-specific variables remain strictly isolated to their parent job.
• Interactive UI Inputs: Adding value, description, and options transforms standard pipeline triggers into user-friendly configuration forms in the GitLab UI.
• Dropdown Enforcement: Use the options keyword for dropdown menus to restrict user inputs to authorized environments or parameters.
• Bash-Like Syntax: Reference variables within scripts using the standard dollar sign syntax ($VARIABLE_NAME).
• Runtime Flexibility: Runtime-injected user inputs override default variable values throughout the entire global pipeline scope.