How to Set Environment Variables in GitLab CI

In this tutorial, you'll learn about How to Set Environment Variables in GitLab CI. We cover key concepts, practical examples, and best practices.

The Problem

Your GitLab CI pipeline needs API keys, database URLs, or configuration values. Hardcoding secrets in .gitlab-ci.yml is insecure. You need a way to pass variables securely to jobs.

Quick Fix

Step 1: Set a variable in the GitLab UI

1. Go to Settings > CI/CD > Variables.
2. Click Add variable.
3. Enter Key: DATABASE_URL and Value: postgres://user:pass@host/db.
4. Check Mask variable to hide the value in logs.
5. Click Add variable.

The variable is available to all jobs in the project.

Step 2: Use the variable in .gitlab-ci.yml

test:
  script:
    - echo "Connecting to $DATABASE_URL"
    - npm test

Masked variables appear as [MASKED] in pipeline logs.

Step 3: Define variables in .gitlab-ci.yml

variables:
  NODE_ENV: production
  LOG_LEVEL: info

build:
  script:
    - npm run build

These are non-sensitive values visible in the pipeline YAML. Anyone with access to the repo can see them.

Step 4: Per-job variable override

variables:
  DEPLOY_ENV: staging

deploy_production:
  variables:
    DEPLOY_ENV: production
  script:
    - ./deploy.sh $DEPLOY_ENV

Variables defined at the job level override global variables.

Step 5: Trigger pipeline with variables

curl -X POST "https://gitlab.com/api/v4/projects/PROJECT_ID/trigger/pipeline" \
  -F "token=TRIGGER_TOKEN" \
  -F "ref=main" \
  -F "variables[DEPLOY_ENV]=production"

Pass variables dynamically when triggering pipelines via the API.

Step 6: Use variable types

variables:
  FILE_VAR:
    value: "long-string-value"
    description: "Enter the API key"

Variables with a description prompt users for input on manual pipeline runs.

Step 7: Protect sensitive variables

In the Variables settings, check:

• Protect variable — only available on protected branches (main, tags).
• Mask variable — hidden in job logs (requires value to match specific format rules).

Step 8: List all available variables in a job

debug:
  script:
    - env | sort

This prints all environment variables available in the job runner, including CI/CD variables and predefined variables like CI_COMMIT_SHA.

Alternative Solutions

Use HashiCorp Vault integration with GitLab CI for rotating secrets and fine-grained access control.

Common Errors

Masked variable not masking: GitLab masks only values that are at least 8 characters, contain at least one letter, and do not match common patterns like URLs. Test by adding the variable and checking a job log.

Variable not available in job: Variables marked as "Protected" are only available on protected branches. Either uncheck "Protected" for non-sensitive variables or run the pipeline on a protected branch.

Multi-line variable values: If your variable contains newlines, use the file type in the GitLab UI or base64-encode the value and decode it in the job script.

Variable override not working: Job-level variables: override global variables:, but CI/CD variables from the UI have lower priority than YAML-defined variables for the same key.

Prevention

• Mask all sensitive variables (API keys, passwords, tokens).
• Use protected variables for production credentials.
• Never hardcode secrets in .gitlab-ci.yml.
• Use group-level variables for secrets shared across projects.