Skip to main content
Mapagam

Using Dynamic Variables and Configuration

1. Using dotenv for Dynamic Variables

Variable Value Description
CI_ENVIRONMENT_NAME production Name of the environment being deployed to
CI_PROJECT_NAME my-app Name of the project in GitLab
CI_COMMIT_REF_NAME main Name of the branch or tag for which the pipeline is created

Example: Setting up dotenv in a GitLab CI job

stages:
  - build
  - deploy

variables:
  ENV_FILE: ".env"

before_script:
  - echo "Installing dotenv package"
  - npm install dotenv

build_job:
  stage: build
  script:
    - echo "Building application"
    - node scripts/build.js

deploy_job:
  stage: deploy
  script:
    - echo "Deploying to $CI_ENVIRONMENT_NAME"
    - node scripts/deploy.js
Note: The .env file should be added to your repository or managed securely via GitLab CI/CD variables.

2. Using Variables from Previous Jobs

Variable Value Description
CI_JOB_ID 12345 Unique identifier for the current job
CI_JOB_NAME build Name of the current job
CI_PIPELINE_ID 67890 Unique identifier for the current pipeline

Example: Accessing job variables in subsequent jobs

job1:
  script:
    - echo "Job ID is $CI_JOB_ID"
    - echo "Pipeline ID is $CI_PIPELINE_ID"
  artifacts:
    reports:
      dotenv: job1.env

job2:
  script:
    - echo "Using variables from previous job"
    - cat job1.env
Note: Artifacts must be explicitly configured to pass variables between jobs.
Warning: Variables set in one job are not automatically available in another unless artifacts or environment variables are used.

3. Generating Dynamic Configuration

Example: Using GitLab CI Variables in Configuration

variables:
  ENVIRONMENT: "staging"
  DATABASE_URL: "postgres://user:pass@db:5432/myapp"

script:
  - echo "Deploying to $ENVIRONMENT"
  - cp .env.$ENVIRONMENT .env
Variable Value Description
CI_ENVIRONMENT_NAME staging Environment name from CI/CD variables
CI_COMMIT_REF_NAME main Branch or tag name
CI_PROJECT_ID 12345 Project identifier
Note: Dynamic configuration values can be set using variables or environment blocks in the CI configuration.
Warning: Avoid hardcoding sensitive values in configuration files. Use GitLab CI variables or secret variables instead.

4. Creating Dynamic Job Names

Property Description Example
job.name Defines the name of a job dynamically using variables or expressions. job.name: "Build-${CI_COMMIT_REF_NAME}"
CI_COMMIT_REF_NAME Variable that contains the branch or tag name. job.name: "Deploy-${CI_COMMIT_REF_NAME}"
CI_PIPELINE_ID Unique identifier for the pipeline. job.name: "Test-${CI_PIPELINE_ID}"

Example: Dynamic Job Name Based on Branch

deploy_to_staging:
  stage: deploy
  script:
    - echo "Deploying to staging environment"
  name: "Deploy to Staging - $CI_COMMIT_REF_NAME"

Example: Using Pipeline ID in Job Name

test_job:
  stage: test
  script:
    - echo "Running tests"
  name: "Test Pipeline $CI_PIPELINE_ID"
Note: Job names must be unique within a pipeline. Using dynamic names helps in identifying jobs easily in the GitLab UI.

5. Using Dynamic Includes

Example: Using include with variables

include:
  - project: 'my-group/my-project'
    file: "${CI_PROJECT_NAME}-pipeline.yml"
    ref: "main"
Property Description Values Notes
include Specifies the configuration to include project, file, ref Can be a string or array of includes
project Path to the project containing the included file group/project Must be a valid project path
file Path to the included YAML file path/to/file.yml Can use variables like ${CI_PROJECT_NAME}
ref Branch, tag, or commit to use for the included file main, v1.0, abc123 Defaults to the default branch if not specified
Note: Dynamic includes support GitLab CI/CD variables, allowing for flexible configuration based on pipeline context.

6. Using Variable Expressions (${VAR:-default})

GitLab CI/CD supports variable expressions using the ${VAR:-default} syntax, which allows you to provide a default value if a variable is not set or is empty.

Expression Description Example
${VAR:-default} Expands to the value of VAR if it is set and not empty; otherwise, uses default. IMAGE_TAG=${CI_COMMIT_REF_NAME:-latest}

Example: Setting a Default Image Tag

IMAGE_TAG=${CI_COMMIT_REF_NAME:-latest}
echo "Using image tag: $IMAGE_TAG"
Note: The ${VAR:-default} syntax is part of Bash parameter expansion and is supported in GitLab CI/CD scripts. It does not require special GitLab syntax or escaping.

7. Creating Conditional Variables

Variable Type Condition Description
CI_PIPELINE_ID System Always Unique identifier for the pipeline
CI_COMMIT_REF_NAME System Branch or Tag Name of the branch or tag being built
CI_ENVIRONMENT_NAME System Environment Name of the environment where the job runs
CUSTOM_VAR User-defined Based on branch Example user variable set conditionally

Example: Setting Conditional Variables in .gitlab-ci.yml

stages:
  - build
  - test
  - deploy

variables:
  CUSTOM_VAR: "default_value"

build_job:
  stage: build
  script:
    - echo "Building..."
  variables:
    CUSTOM_VAR: "build_value"

test_job:
  stage: test
  script:
    - echo "Testing with $CUSTOM_VAR"
  variables:
    CUSTOM_VAR: "test_value"

deploy_job:
  stage: deploy
  script:
    - echo "Deploying to $CI_ENVIRONMENT_NAME"
  variables:
    CUSTOM_VAR: "deploy_value"
Note: Variables defined in a job's variables section override those defined at the global level.

8. Using Multi-Line Variables

Variable Value Description
CI_PIPELINE_ID 12345 Unique identifier for the pipeline
CI_COMMIT_SHA abc123def456... Full commit SHA of the current pipeline

Example: Setting a Multi-Line Variable in GitLab CI

variables:
  MULTI_LINE_VAR: |
    This is line one
    This is line two
    This is line three
Note: Multi-line variables are useful for configuration files or scripts that require multiple lines of content.
Warning: Be cautious with multi-line variables in sensitive contexts as they may expose secrets if not handled properly.

9. Implementing Variable Inheritance

Variable Scope Inheritance Path Description
project CI_PROJECT_ID → CI_PROJECT_NAME Variables defined at project level are inherited by all jobs in the pipeline.
group CI_GROUP_ID → CI_GROUP_NAME Variables set at group level are available to all projects within the group.
instance CI_INSTANCE_ID Instance-wide variables are accessible across all groups and projects.

Example: Inheriting Variables in a Job

job_with_inherited_vars:
  script:
    - echo "Project name: $CI_PROJECT_NAME"
    - echo "Group name: $CI_GROUP_NAME"
Note: Variable inheritance follows a hierarchy: instance > group > project > job. Variables defined at a higher level can be overridden at lower levels.

10. Implementing Dynamic Environments

Environment Type Description Usage
environment.name string Name of the environment Used in UI and logs to identify the environment
environment.url string URL to access the environment Used in notifications and deployment tracking
environment.auto_stop_in string Time after which environment is automatically stopped Used to manage resource usage and cost

Example: Environment Configuration

deploy_staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.example.com
    auto_stop_in: 1 day
  script:
    - echo "Deploying to staging environment"
Note: Environments can be configured to auto-stop after a specified time to prevent resource waste.

Example: Dynamic Environment Variables

deploy_production:
  stage: deploy
  environment:
    name: production-$CI_COMMIT_SHORT_SHA
    url: https://prod.example.com/$CI_COMMIT_SHORT_SHA
  script:
    - echo "Deploying to production with SHA: $CI_COMMIT_SHORT_SHA"
Warning: Ensure that environment URLs are properly secured and accessible only to authorized users.
Environment Variable Value Usage
CI_COMMIT_SHORT_SHA abc1234 Short commit hash for dynamic environment naming
CI_ENVIRONMENT_NAME staging Name of the current environment
CI_ENVIRONMENT_URL https://staging.example.com URL of the current environment

Was this article helpful?

Related Cheat Sheets