Gitlab Pipeline – variables – What is variables in GitLab CI/CD?

Here’s a basic GitLab CI/CD YAML (.gitlab-ci.yml) example that demonstrates how the variables configuration option is used, along with an explanation.

Variables in GitLab CI/CD allow you to define and store values that can be reused throughout your pipeline. This is useful for configuration settings, environment-specific values, or any data you want to make accessible to your jobs.

You can define variables at several levels:

• Globally: Using the top-level variables keyword. These are available to all jobs.
• Job-level: Defined within a specific job. These are only available to that job and can override global variables with the same name.
• In the GitLab UI: At the project, group, or instance level (Settings > CI/CD > Variables). These are generally recommended for sensitive information.

This example will focus on YAML-defined global and job-level variables.

Example .gitlab-ci.yml with variables:

YAML

# .gitlab-ci.yml

# 1. Global Variables: Available to all jobs
variables:
  GLOBAL_APP_NAME: "MyAwesomeApp"
  GLOBAL_BUILD_VERSION: "1.0.0"
  # Note: For sensitive data like API keys, use protected variables in GitLab UI settings, not here.

stages:
  - build
  - test
  - deploy

# Job 1: Uses global variables and a predefined CI variable
build_job:
  stage: build
  variables: # 2. Job-level variables for build_job
    BUILD_TARGET: "linux/amd64" # Specific to this job
  script:
    - echo "--- Build Job ---"
    - echo "Building application: $GLOBAL_APP_NAME"
    - echo "Build version: ${GLOBAL_BUILD_VERSION}" # Another way to reference variables
    - echo "Build target platform: $BUILD_TARGET"
    - echo "This job is running on branch: $CI_COMMIT_REF_NAME" # Example of a predefined CI variable

# Job 2: Uses global variables and overrides one
test_job:
  stage: test
  variables: # 2. Job-level variables for test_job
    GLOBAL_BUILD_VERSION: "1.0.1-beta" # Overrides the global variable for this job only
    TEST_FRAMEWORK: "pytest"
  script:
    - echo "--- Test Job ---"
    - echo "Testing application: $GLOBAL_APP_NAME"
    - echo "Testing version: $GLOBAL_BUILD_VERSION" # This will show "1.0.1-beta"
    - echo "Using test framework: $TEST_FRAMEWORK"
    - echo "Predefined variable CI_JOB_STAGE: $CI_JOB_STAGE"

# Job 3: Only uses global variables
deploy_job:
  stage: deploy
  script:
    - echo "--- Deploy Job ---"
    - echo "Deploying application: $GLOBAL_APP_NAME"
    - echo "Deploying version: $GLOBAL_BUILD_VERSION" # This will show the global "1.0.0"
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Only run deploy for the default branch

Code language: PHP (php)

Explanation:

1. Global variables: Block:
   • variables: at the top level of your .gitlab-ci.yml file defines variables that are accessible to all jobs within that pipeline by default.
   • GLOBAL_APP_NAME: "MyAwesomeApp": Defines a variable named GLOBAL_APP_NAME with the value “MyAwesomeApp”.
   • GLOBAL_BUILD_VERSION: "1.0.0": Defines GLOBAL_BUILD_VERSION.
   • Security Note: It’s crucial to remember not to store sensitive data like passwords, API keys, or private tokens directly in your .gitlab-ci.yml file. For such data, use GitLab’s CI/CD variable settings in the UI (Project > Settings > CI/CD > Variables), where you can mark them as “Protected” (only available to protected branches/tags) or “Masked” (hidden in job logs).
2. Job-Level variables: Block:
   • You can define variables inside a specific job’s configuration. These variables are only available within that job.
   • In build_job:
     • BUILD_TARGET: "linux/amd64": This variable is only available to build_job.
   • In test_job:
     • GLOBAL_BUILD_VERSION: "1.0.1-beta": This overrides the global GLOBAL_BUILD_VERSION variable specifically for test_job. Other jobs like build_job and deploy_job will still use the global value (“1.0.0”).
     • TEST_FRAMEWORK: "pytest": A new variable specific to test_job.
3. Accessing Variables in script Sections:
   • Variables are accessed in script blocks using the $VARIABLE_NAME syntax or ${VARIABLE_NAME} (the curly braces can be useful for clarity, especially when a variable is adjacent to other characters).
   • Examples: echo "Building application: $GLOBAL_APP_NAME" or echo "Build version: ${GLOBAL_BUILD_VERSION}".
4. Predefined CI/CD Variables:
   • GitLab automatically provides a large set of predefined variables that give you information about the job, pipeline, project, commit, runner, etc.
   • $CI_COMMIT_REF_NAME: In build_job, this shows the branch or tag name for which the pipeline is running.
   • $CI_JOB_STAGE: In test_job, this shows the stage of the current job (which would be “test”).
   • There are many more like $CI_PROJECT_DIR, $CI_PIPELINE_ID, $CI_COMMIT_SHA, etc. You can find a full list in the GitLab documentation.
5. Variable Precedence (Order of Overriding):GitLab CI/CD variables have a specific order of precedence. If the same variable name is defined in multiple places, one will override the others:
   1. Variables from triggers, scheduled pipelines, or manual pipeline runs (highest precedence).
   2. Project-level variables (defined in GitLab UI: Settings > CI/CD).
   3. Group-level variables (defined in GitLab UI for a group).
   4. Instance-level variables (defined by GitLab admin).
   5. YAML job-level variables.
   6. YAML global variables.
   7. Variables from inherited configurations (e.g., from include or extends).
   8. Predefined CI/CD variables (lowest precedence, generally cannot be overridden by user-defined variables with the same name, but some can be).
   So, a job-level variable in your YAML will override a global YAML variable with the same name. A variable set in the GitLab UI (Project Settings) will override both job-level and global YAML variables.

Use Cases for Variables:

• Configuration: Defining build configurations, deployment targets, feature flags.
• Environment Settings: Specifying database URLs, service endpoints for different environments (dev, staging, prod) – often in conjunction with environment-specific variables set in the UI.
• Reusability: Storing common values used in multiple scripts or jobs.
• Secrets/Credentials (handled securely): Storing API keys, tokens, passwords. Always use GitLab UI variables marked as “Protected” and/or “Masked” for these, not plain text in YAML.

Using variables effectively can make your GitLab CI/CD pipelines more flexible, maintainable, and secure.