Managing Pipeline Variables and Secrets

1. Defining Pipeline Variables

Variable Type	Name	Value	Notes
Project Variable	`API_KEY`	`secret123`	Defined in Project Settings > CI/CD > Variables
Group Variable	`DB_PASSWORD`	`group_secret`	Defined in Group Settings > CI/CD > Variables
Environment Variable	`ENVIRONMENT`	`production`	Set in environment-specific variables
CI/CD Variable	`CI_COMMIT_REF_NAME`	`main`	Built-in GitLab CI variable

Example: Setting a Project Variable in .gitlab-ci.yml

variables:
  API_KEY: "secret123"
  ENVIRONMENT: "production"

Note: Project variables are accessible to all jobs in the pipeline. Group variables are available to all projects within a group.

2. Setting Job-Level Variables

Variable	Value	Description
job_variable_name	`job_variable_value`	Defines a variable specific to the job scope.

Example: Setting a Job-Level Variable

job_name:
  variables:
    ENVIRONMENT: production
    DEBUG_MODE: "false"

Note: Job-level variables are only available within the job they are defined in.

3. Using Environment Variables in Scripts ($VAR)

Variable	Usage	Description
CI_PIPELINE_ID	`$CI_PIPELINE_ID`	Unique identifier for the current pipeline
CI_JOB_ID	`$CI_JOB_ID`	Unique identifier for the current job
CI_COMMIT_SHA	`$CI_COMMIT_SHA`	Full commit SHA of the current pipeline
CI_PROJECT_NAME	`$CI_PROJECT_NAME`	Name of the project
CI_REGISTRY_USER	`$CI_REGISTRY_USER`	Username for container registry authentication

Example: Using CI_PIPELINE_ID in a script

echo "Pipeline ID is: $CI_PIPELINE_ID"

Example: Using CI_COMMIT_SHA in a script

echo "Commit SHA: $CI_COMMIT_SHA"
git log --oneline -n 1

Note: Environment variables are automatically available in all job scripts and can be overridden by variables in the .gitlab-ci.yml file.

4. Expanding Variable References ($VAR, ${VAR})

Reference Type	Format	Description	Example
Simple Variable	`$VAR`	Expands to the value of the variable VAR	`echo $CI_PIPELINE_ID`
Brace Variable	`${VAR}`	Same as $VAR but allows for more complex expressions	`echo ${CI_COMMIT_SHA}`
Nested Variables	`${VAR1_${VAR2}}`	Allows dynamic variable names based on other variables	`${VAR_${ENV}}`

Example: Using Variable References in Scripts

script:
  - echo "Pipeline ID: $CI_PIPELINE_ID"
  - echo "Commit SHA: ${CI_COMMIT_SHA}"
  - echo "Branch Name: $CI_COMMIT_REF_NAME"

Note: Variable expansion happens in the context of the runner environment, so ensure variables are defined before use.

5. Masking Sensitive Variables

Variable	Type	Description	Masking
CI_JOB_TOKEN	System	Token for accessing GitLab resources during job execution	NEW
CI_REGISTRY_PASSWORD	Environment	Password for container registry authentication	Automatically masked
API_TOKEN	User-defined	Custom sensitive token used in scripts	Manually masked

Example: Setting a masked variable in .gitlab-ci.yml

variables:
  API_TOKEN: "secret123"
  DATABASE_PASSWORD: "dbpass456"

Note: Variables set in the GitLab UI or via API are automatically masked in logs if they contain sensitive data.

Warning: Never output masked variables to job logs or use them in echo/print statements.

6. Protecting Variables

Variable	Protection Status	Description
CI_ENVIRONMENT_NAME	DEPRECATED	Environment name; deprecated in favor of `CI_ENVIRONMENT_SLUG`
CI_JOB_ID	Protected	Unique identifier for the job; automatically protected
CI_PIPELINE_ID	Protected	Unique identifier for the pipeline; automatically protected
CI_REGISTRY_PASSWORD	Protected	Password for GitLab Container Registry; automatically protected

Example: Setting a Protected Variable

variables:
  PROTECTED_VAR: "secret_value"
  <span class="highlight">CI_PIPELINE_ID</span>: <span class="highlight">12345</span>

Note: Protected variables are not exposed in job logs or web UI for visibility, but they can still be accessed by scripts within the job.

Warning: Ensure that any sensitive data stored in protected variables is not inadvertently logged or echoed to the console.

7. Setting Variable Scope

Variable Type	Scope	Description	Usage Example
CI/CD Variables	Project Level	Available to all jobs in a project	`PROJECT_VAR=project_value`
CI/CD Variables	Group Level	Available to all jobs in a group of projects	`GROUP_VAR=group_value`
CI/CD Variables	Instance Level	Available to all jobs in the entire GitLab instance	`INSTANCE_VAR=instance_value`
CI/CD Variables	Job Level	Available only to the specific job where defined	`job:` `variables:` `JOB_VAR=job_value`
CI/CD Variables	Environment Level	Available to jobs in a specific environment	`environment:` `name: production` `variables:` `ENV_VAR=env_value`

Example: Setting Project-Level Variables in .gitlab-ci.yml

variables:
&nbsp;&nbsp;PROJECT_VAR: "project_value"
&nbsp;&nbsp;ANOTHER_VAR: "another_value"

Example: Setting Job-Level Variables in .gitlab-ci.yml

job1:
&nbsp;&nbsp;script:
&nbsp;&nbsp;&nbsp;&nbsp;- echo "$JOB_VAR"
&nbsp;&nbsp;variables:
&nbsp;&nbsp;&nbsp;&nbsp;JOB_VAR: "job_specific_value"

Note: Variable scope follows a hierarchy from job level to instance level, with job-level variables taking precedence over project-level ones.

8. Using File-Type Variables

Variable Type	Usage	Notes
file	`FILE_VAR=@/path/to/file`	Stores file content as a variable value. Can be used in scripts or as environment variables.
file	`FILE_VAR=@./config.json`	Relative path from the project root. File content is base64-encoded when passed to scripts.

Example: Using file-type variables in a script

script:
  - echo "Content of config.json: $FILE_VAR"

Note: The file content is base64-encoded when passed to the script. You may need to decode it before use.

9. Accessing Project and Group Variables

Variable Type	Scope	Access Method	Description
Project Variables	Project-level	`$VAR_NAME` or `${VAR_NAME}`	Available to all jobs in the project. Set via UI or `.gitlab-ci.yml`.
Group Variables	Group-level	`$GROUP_VAR_NAME` or `${GROUP_VAR_NAME}`	Available to all projects within the group. Set in Group settings.
Protected Variables	Project/Group-level	`$PROTECTED_VAR`	Only accessible in protected branches or tags. Requires `protected: true` in config.

Example: Using Project Variables in a Job

job_name:
  script:
    - echo "Deploying to $DEPLOY_ENV server"
    - echo "Database URL: $DB_URL"

Example: Using Group Variables

deploy_job:
  script:
    - echo "Using group variable: $GROUP_API_KEY"

Note: Variables are case-sensitive and must be defined before use. Project variables take precedence over group variables with the same name.

10. Using Raw Variables

Variable	Value	Description
CI_PIPELINE_ID	`12345`	Unique identifier for the current pipeline
CI_COMMIT_SHA	`abc123def456`	Full commit SHA of the current pipeline
CI_PROJECT_NAME	`my-app`	Name of the project being built

Example: Using raw variables in a script

#!/bin/bash
echo "Pipeline ID: $CI_PIPELINE_ID"
echo "Commit SHA: $CI_COMMIT_SHA"
echo "Project Name: $CI_PROJECT_NAME"