Lesson 04 intermediate

Variables and Secrets in GitLab CI

Predefined variables, variables in .gitlab-ci.yml, project and group CI/CD settings, masked, hidden and protected variables, file variables, precedence, environment-scoped values, the job token, and where secrets should really live, including external secret managers and GitLab Secrets Manager.

Pipelines need configuration: which Node.js version to use, which URL to deploy to, which API key to call. Some of those values are harmless, some would hurt if they leaked. GitLab gives you one mechanism, CI/CD variables, with several places to define them and several ways to protect them. This lesson shows where each kind of value belongs.

Variables are environment variables

Inside a job, every CI/CD variable is an ordinary environment variable. You read it the same way in any shell command:

show-context:
  script:
    - echo "Project:  $CI_PROJECT_PATH"
    - echo "Branch:   $CI_COMMIT_BRANCH"
    - echo "Commit:   $CI_COMMIT_SHA"
    - echo "Pipeline: $CI_PIPELINE_SOURCE"

Programs read them too: Node.js through process.env, Python through os.environ, the AWS CLI through its own AWS_* variables.

Predefined variables

GitLab sets well over a hundred variables in every job. These are the ones you will use most:

VariableValue
CI_COMMIT_SHA / CI_COMMIT_SHORT_SHAFull and 8-character commit hash
CI_COMMIT_BRANCHBranch name (empty for tag and merge request pipelines)
CI_COMMIT_TAGTag name, only in tag pipelines
CI_COMMIT_REF_SLUGBranch or tag name made safe for URLs and hostnames
CI_DEFAULT_BRANCHUsually main
CI_PIPELINE_SOURCEWhy the pipeline started: push, merge_request_event, schedule, web, api, trigger…
CI_MERGE_REQUEST_IIDMerge request number, in merge request pipelines
CI_PROJECT_DIRWhere the repository is checked out
CI_REGISTRY_IMAGEAddress of the project’s container registry
CI_JOB_TOKENShort-lived token for this job (see below)
CI_ENVIRONMENT_NAMEEnvironment the job deploys to

The full list lives in the GitLab documentation under Predefined CI/CD variables. When in doubt, run env | sort in a throwaway job, but never in a job that also has secrets, because the log would show them.

Variables in .gitlab-ci.yml

Non-sensitive configuration belongs in the file, where it is reviewed and versioned with the code:

variables:
  NODE_ENV: production
  API_PORT: "8080"

unit-tests:
  variables:
    NODE_ENV: test
  script:
    - echo "Running in $NODE_ENV on port $API_PORT"

Top-level variables apply to every job; job-level ones override them. Quote numbers so YAML does not turn "08" into something surprising.

Variables that people can choose

Add a description and an optional list of options, and GitLab shows a form field when someone runs the pipeline manually:

variables:
  DEPLOY_TARGET:
    value: staging
    options: [staging, production]
    description: "Where the manual pipeline deploys"

For reusable configuration, lesson 12 shows spec:inputs, which are typed and validated before the pipeline is created.

Project and group variables

Values that must not be in the repository go in Settings → CI/CD → Variables, on the project or on a group so every project under it inherits them. Each variable has a few switches:

SettingEffect
Visibility: VisibleShown in job logs if printed
Visibility: MaskedReplaced with [MASKED] in job logs
Visibility: Masked and hiddenMasked, and the value can never be viewed again in the UI after saving
Protect variableOnly available to pipelines on protected branches and tags
Expand variable referenceWhether $OTHER inside the value is expanded
Type: FileThe value is written to a temporary file; the variable holds the path
EnvironmentsLimit the variable to one environment, such as production

Masking needs a value that is at least eight characters long and uses only characters GitLab can safely match. It is a safety net against accidental echo, not a security boundary: a malicious script can still send the value somewhere.

Protected variables are the real boundary

Anyone who can push a branch can change .gitlab-ci.yml on that branch and print every variable the job receives. Protected variables only reach pipelines on protected branches like main, which only maintainers can push or merge to. Production credentials must always be protected.

feature branch pipeline   ──▶ sees STAGING_URL           (not protected)
main branch pipeline      ──▶ sees STAGING_URL, PROD_DB_PASSWORD (protected)

File variables

Many tools want a file, not a string: kubeconfigs, service account JSON keys, TLS certificates. Choose Type: File and GitLab writes the value to a temporary file and puts the file path in the variable:

deploy:
  script:
    - kubectl --kubeconfig "$KUBECONFIG_STAGING" get pods

Environment-scoped variables

The same variable name can hold different values per environment. Define API_URL twice, scoped to staging and to production, and each deploy job receives the right one based on its environment: (lesson 7). No if statements needed.

Which value wins?

When the same name is defined in several places, the most specific source wins. From highest to lowest priority:

  1. Variables set when running a pipeline manually, by a trigger, a schedule or the API
  2. Project variables
  3. Group variables (the closest subgroup wins)
  4. Instance variables (self-managed GitLab)
  5. Job-level variables in .gitlab-ci.yml
  6. Top-level variables in .gitlab-ci.yml
  7. Predefined variables

The practical consequence: a project setting overrides the default in your YAML, which is useful for per-project tweaks and confusing when you forget it exists. If a value is not what you expect, check the settings first.

Pipeline variables may be restricted. Because they outrank everything else, recent GitLab versions let you limit who may pass variables when running a pipeline, and new projects often start with the strict setting. If a manual run rejects or ignores your override, check the minimum role allowed to use pipeline variables under Settings → CI/CD → Variables.

The job token

Every job gets CI_JOB_TOKEN, a token that is valid only while the job runs and has the permissions of the user who started the pipeline, limited to a set of APIs. Use it instead of personal tokens to:

  • log in to the project’s container registry (lesson 8);
  • download packages from the GitLab package registry;
  • trigger downstream pipelines and fetch artifacts from other projects (lesson 12).
fetch-shared-config:
  script:
    - >
      curl --fail --header "JOB-TOKEN: $CI_JOB_TOKEN"
      "$CI_API_V4_URL/projects/orbit%2Fshared-config/packages/generic/config/1.0.0/app.json"
      -o app.json

Access from one project to another is controlled by the target project’s job token allowlist (Settings → CI/CD → Job token permissions). Only add the projects that really need access.

Where secrets should live

CI/CD variables are fine for a handful of secrets. As the number of services and environments grows, teams move to a dedicated secret store and let the pipeline fetch values at runtime. GitLab supports this with the secrets keyword:

deploy-production:
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
    DATABASE_PASSWORD:
      vault: orbit/production/db/password@secret
      file: false
  script:
    - ./scripts/migrate.sh

The job proves who it is with a short-lived OIDC ID token (id_tokens), Vault checks the project, branch and environment in that token, and returns only the secrets that pipeline is allowed to read. The same pattern works with Azure Key Vault, Google Secret Manager and AWS Secrets Manager. The secrets keyword requires GitLab Premium or Ultimate.

GitLab Secrets Manager, introduced as a beta in GitLab 19.0 for Premium and Ultimate, stores secrets inside GitLab itself and scopes each one to the jobs, branches and environments allowed to read it. If you are on those tiers it is worth watching; on Free, protected and masked variables plus OIDC for cloud access (lesson 11) cover most needs.

The best secret is no secret

For cloud deploys, the safest option is often not to store a key at all. The same id_tokens mechanism lets a job exchange its GitLab-signed token for temporary cloud credentials from AWS, Google Cloud or Azure. Nothing long-lived sits in GitLab to leak. Lesson 11 does exactly that for Orbit on AWS.

Rules for handling secrets

  • Never commit secrets, not even in a “temporary” commit. Git history keeps them forever.
  • Mark every secret masked and hidden and protected.
  • Scope production secrets to the production environment.
  • Never run env, set -x or printenv in jobs that receive secrets.
  • Prefer short-lived OIDC credentials over static keys.
  • Rotate anything that might have leaked. Masking only hides values from logs.
  • Turn on secret detection (lesson 10) so leaked keys are caught in merge requests.

Exercise

A developer pushes a feature branch that changes .gitlab-ci.yml to run echo $PROD_DB_PASSWORD | base64. The variable is masked but not protected. What happens?

  1. Nothing leaks, because masking prevents it
  2. The encoded password shows up in the job log, because masking only matches the exact value
  3. GitLab blocks the pipeline because the file changed
  4. The job fails because base64 is not installed
Show answer

Answer: B. Masking replaces the literal value in logs, so any transformation defeats it. Only protecting the variable keeps it out of feature-branch pipelines, which is why production secrets must be protected.

Exercise

STAGING_URL is set in the project’s CI/CD settings and also under variables: at the top of .gitlab-ci.yml. Which value does a job see?

  1. The one in .gitlab-ci.yml, because the file is more recent
  2. The project setting, because it has higher precedence than YAML variables
  3. Both, joined with a space
  4. The pipeline fails with a duplicate variable error
Show answer

Answer: B. Settings-level variables override variables defined in the YAML file. Only manual, triggered, scheduled or API pipeline variables rank higher.

Key takeaways

  • Every CI/CD variable is an environment variable inside the job.
  • Non-sensitive configuration goes in .gitlab-ci.yml; secrets go in settings, a secret manager or nowhere at all.
  • Masked hides values from logs; protected keeps them away from unprotected branches. Production secrets need both.
  • File variables suit kubeconfigs and certificates; environment scopes give one name different values.
  • CI_JOB_TOKEN and OIDC ID tokens replace long-lived personal and cloud tokens.

FAQ

Is a masked variable safe?

It is safe from accidental printing, not from a script that deliberately sends it elsewhere. Combine masking with protection, environment scopes and limited push rights to protected branches.

Why is my protected variable empty in a merge request pipeline?

Merge request pipelines run on the source branch, which is usually not protected, so protected variables are not passed. That is by design. Deploy jobs that need them should run on the protected target branch after the merge.

Can I use variables inside other variables?

Yes, $OTHER and ${OTHER} expand inside variable values unless expansion is turned off for that variable. Turn it off for values that contain a literal $, such as some passwords.

How do I pass a variable from one job to another?

Write KEY=value lines to a file and save it as a dotenv report artifact (artifacts:reports:dotenv: build.env). Jobs that depend on it receive those values as variables. Lesson 7 uses this to pass a dynamic environment URL.

Should I use group variables or project variables?

Group variables for values shared by many projects, such as a registry mirror or a company-wide token. Project variables for anything specific to one application. Fewer copies means fewer secrets to rotate.

↑ ↓ navigate Enter open Esc close