GitLab CI/CD variable empty or can't be masked: causes and fixes

By Melih Toksari, developer of MergeBell · Updated · 5 min read

Short answer

A GitLab CI/CD variable is empty when the job isn't allowed to see it. Protected variables reach only pipelines on protected branches and tags. A variable with an environment scope reaches only jobs with a matching environment. The parent project's variables never reach a fork's pipeline. Values exported in a script don't survive into after_script or later jobs: write them to a file, or pass them to later jobs with a dotenv report. A value that's there but wrong usually comes from precedence: a project variable outranks anything in .gitlab-ci.yml. To be masked, a value must be one line, with no spaces, and at least 8 characters long.

The job’s script prints nothing where your token should be, or GitLab refuses to save a variable as masked. Both have a short list of causes. Here they are for GitLab 19.5, with the fix for each.

Check what the job sees

Print whether the variable is set, never its value, next to the facts that decide what a job gets:

debug-variables:
  script:
    - echo "DEPLOY_TOKEN is ${DEPLOY_TOKEN:+set}"
    - echo "ref $CI_COMMIT_REF_NAME, protected $CI_COMMIT_REF_PROTECTED, environment $CI_ENVIRONMENT_NAME"

${DEPLOY_TOKEN:+set} prints set when the variable has a value, and nothing when it doesn’t. CI_COMMIT_REF_PROTECTED says whether the branch or tag is protected, and CI_ENVIRONMENT_NAME is only set for a job with environment:name. The export command lists every variable the job has, with masked ones shown as [MASKED], but it prints everything else in full.

Why the variable is empty

  • It’s protected, and the branch isn’t. A protected variable reaches only pipelines on protected branches and tags. Run the job on a protected branch, protect the branch, or clear Protect variable if the value isn’t secret. Merge request pipelines have extra rules: see merge request pipelines.
  • Its environment scope doesn’t match. A variable scoped to production reaches only jobs with an environment of production; the default scope, *, reaches every job. Add environment: production to the job, or widen the scope. Don’t use scoped variables in rules or include: GitLab may not have them when it creates the pipeline.
  • The pipeline runs in a fork. A merge request from a fork runs its pipeline in the fork, with the fork’s variables. A member of the parent project can run it in the parent project from the merge request’s Pipelines tab, after checking the changes.
  • It was set in the script. before_script and script share a shell, but after_script runs in a new one, and every job starts fresh. A value you export is gone by then. For after_script, write the value to a file in script and read it back; for later jobs, use a dotenv report.
  • A job variable reuses a default’s name. With MY_VAR: $MY_VAR in a job, the job’s own variable hides the default one, so nothing expands: the job gets the literal text $MY_VAR. Give it a different name.
  • rules:if can’t see it. Rules are checked when GitLab creates the pipeline, before any job runs. Variables made in a script, or job values such as CI_JOB_ID, don’t exist yet.

Pass a value to later jobs

build:
  stage: build
  script:
    - echo "BUILD_VERSION=v1.0.0" >> build.env
  artifacts:
    reports:
      dotenv: build.env

test:
  stage: test
  script:
    - echo "$BUILD_VERSION"

Jobs in later stages get the variable. A job that uses dependencies or needs gets dotenv variables only from the jobs it lists; passing artifacts between jobs has the rules.

The value is there, but wrong

Another source wins. GitLab uses the highest-precedence value, from highest to lowest:

  1. Variables from a pipeline execution or scan execution policy, for the jobs it adds.
  2. Manual job variables, set when you run a manual job.
  3. Pipeline variables: from New pipeline, a schedule, the API, a trigger, the ci.variable push option, or an upstream pipeline.
  4. Project variables, then group variables (the closest subgroup first), then instance variables.
  5. Variables from dotenv reports.
  6. .gitlab-ci.yml: rules:variables, then the job’s variables, then workflow:rules:variables, then the top-level variables.

So a project variable DEPLOY_TARGET set to production beats DEPLOY_TARGET: "review" in the job.

A $ in the value. Since GitLab 18.6, variables added in the settings aren’t expanded by default. If Expand variable reference is selected on a visible variable, a password like pa$word loses $word. Clear the option. (A masked value with expansion can’t contain $ at all.) In .gitlab-ci.yml, write $$ for a literal $, or set expand: false on the variable.

It’s a file variable. For the File type, the variable holds the path to a temporary file with the value inside. Pass it to tools that want a file, like --certificate-authority="$KUBE_CA_PEM", or read it with cat "$KUBE_CA_PEM".

GitLab won’t mask it

Unable to create masked variable because:
The value must have 8 characters.

A masked value must be:

  • a single line, with no spaces;
  • at least 8 characters long;
  • with Expand variable reference selected, made only of letters, digits and _ : @ - + . ~ = /.

A value with other characters gets “The value cannot contain the following characters:” and the list. GitLab’s docs add that the value can’t match the name of another CI/CD variable.

  • Masked is the default for new variables since GitLab 18.3.
  • Masked and hidden can only be chosen when you create a variable, and no one can see the value in the settings after that.
  • Masking only replaces exact matches with [MASKED] in the log. An escaped or encoded copy of the value prints in full, so masking doesn’t stop a script that wants to leak it. Keep secrets out of .gitlab-ci.yml, where anyone who can read the repository sees them.

“Insufficient permissions to set pipeline variables”

Running a pipeline with variables needs the role set in Settings › CI/CD › Variables › Minimum role to use pipeline variables. That covers the New pipeline form, the API, triggers and the ci.variable push option. Saving a schedule with variables is checked too, with a different message: “The current user is not authorized to set pipeline schedule variables”.

Where Default for new projects
GitLab.com, new projects in new namespaces no_one_allowed: only the Owner can change it
GitLab Self-Managed and GitLab Dedicated The top-level group’s Default role to use pipeline variables: Developer, or No one allowed if an administrator cleared Allow pipeline variables by default in new groups

A trigger job sends pipeline variables too, including the top-level variables it inherits. If it starts a pipeline in another project that restricts them, the trigger fails with “downstream pipeline can not be created, Insufficient permissions to set pipeline variables”. Remove the trigger job’s variables, or add inherit: variables: false.

On your phone

MergeBell shows a job’s log as GitLab stores it, so a masked value reads [MASKED] on your phone too, and the ${VAR:+set} check above is easy to read in a live log. Retry and manual jobs are on the free tier and use your own GitLab token. Variables themselves live in Settings › CI/CD › Variables in GitLab in a browser, and need the Maintainer role. For running a manual job, see how to run a manual job in GitLab CI/CD.

Frequently asked questions

Why is my GitLab CI/CD variable empty?

Usually it's protected and the pipeline runs on an unprotected branch: protected variables reach only pipelines on protected branches and tags. The other common causes are an environment scope that doesn't match the job's environment, a pipeline that runs in a fork, and a value exported in script that's read in after_script or another job.

Why can't I mask a GitLab CI/CD variable?

GitLab masks only values that are a single line with no spaces and at least 8 characters long. If Expand variable reference is selected, the value can also only use letters, digits and the characters _ : @ - + . ~ = /. Otherwise GitLab says "Unable to create masked variable because:" and names the rule, such as "The value must have 8 characters."

Why does my GitLab CI/CD variable have the wrong value?

When a variable is set in several places, the highest-precedence value wins. Pipeline variables, from New pipeline, a schedule or the API, beat project variables. Project variables beat group and instance variables, and all of them beat values in .gitlab-ci.yml. So a project variable DEPLOY_TARGET=production overrides DEPLOY_TARGET in the file.

How do I pass a variable from one GitLab job to the next?

Write it to a file as NAME=value, one per line, and add the file under artifacts:reports:dotenv. Jobs in later stages get it as a variable; a job that uses dependencies or needs gets it only from the jobs it lists. A value set with export lasts only for that job's before_script and script.

Why do I get "Insufficient permissions to set pipeline variables"?

Your role is below the project's Minimum role to use pipeline variables, in Settings › CI/CD › Variables. On GitLab.com, new projects in new namespaces default to no_one_allowed, and only the Owner can change that. On GitLab Self-Managed, new projects take their top-level group's default, developer unless an administrator changed it. A trigger job that sends variables to another project's pipeline can get the same error from that project.

Sources

Checked against these pages on 3 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.

Do this from your phone with MergeBell

Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.

Get MergeBell for iPhoneGet MergeBell for Android

On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.