Gitlab CI Variables [Complete Guide]

GitLab CI is a solid choice for building and deploying applications. You get automation, full change tracking, and a pipeline system that handles the heavy lifting.

No matter the size of your project, you will need variables. Maybe you want to control how a script behaves, or maybe you need to pass configuration that differs between environments. Either way, understanding how GitLab CI variables work is worth your time.

There are several ways to declare variables, and the method you pick determines the scope. A variable defined in your .gitlab-ci.yml is not the same as one defined at the group level. We will walk through each option so you can pick the right approach.

If your goal is to change pipeline behavior based on conditions (merge requests, specific branches, and so on), check out GitLab Rules alongside variables.

GitLab CI Variables

CI/CD variables are a specific kind of environment variable. They are available to your pipeline jobs and serve a few practical purposes:

• Keep hard-coded values out of your .gitlab-ci.yml file.
• Control which jobs run and when.
• Store values that your build scripts need.
• Define a value once instead of repeating it across every branch.

GitLab also ships with a set of predefined CI/CD variables you can use right away. Beyond that, you can define custom variables in several places:

• In the .gitlab-ci.yml file itself.
• As project-level CI/CD variables.
• As group-level CI/CD variables.
• As instance-level CI/CD variables (admin only).

Let us look at each one.

Define variables in the .gitlab-ci.yml file

To create a variable directly in your pipeline config, use the variables keyword. You can place it at the top level (global scope) or inside a specific job.

A top-level variable is available to every job. A job-level variable is only visible to that job.

variables:
  GLOBAL_VAR: "This variable is visible for all jobs."

job_1:
  variables:
    JOB_LOCAL_VAR: "Only job_1 can use this variable."
  script:
    - echo "$GLOBAL_VAR" and "$JOB_LOCAL_VAR"

Variables in the .gitlab-ci.yml file are plain text in your repository. Anyone with read access can see them. Use this for non-sensitive configuration like JAVA_HOME or a database URL. For passwords, API keys, and other secrets, use project or group CI/CD variables instead.

Variables defined this way are also available inside service containers.

You can also override variable values when running a pipeline manually.

There are two variable types: env_var (the default) and file. A file-type variable stores its value in a temporary file and sets the environment variable to the file path instead. This is useful for tools that expect a file as input, like kubectl or the AWS CLI.

The shell that the runner uses has its own set of reserved variable names. Make sure your variable names do not conflict.

Also note that pipelines triggered from forked projects cannot access CI/CD variables from the parent project. The one exception is when you open a merge request from a fork back into the parent.

Using variables inside other variables

You can reference one variable inside another:

variables:
  BASE_URL: "https://api.example.com"
  FULL_ENDPOINT: "$BASE_URL/v1/status"

check_status:
  script:
    - curl "$FULL_ENDPOINT"

GitLab expands $BASE_URL when the job runs, so $FULL_ENDPOINT resolves to https://api.example.com/v1/status.

Take some minutes, and visit:

Gitlab Tutorials

Project CI/CD variables

You can define variables in a project’s settings. Only project members with the Maintainer role (or higher) can create or edit them. This is a good way to keep secrets out of your codebase.

To add a project variable:

1. Go to your project’s Settings > CI/CD, then expand the Variables section.
2. Select Add variable and fill in the key, value, and optional flags.

Group CI/CD variables

If you want a variable available to every project in a group, define it at the group level. This is handy for shared credentials like SSH keys, registry logins, or common passwords.

To create a group variable:

1. In your group, go to Settings > CI/CD and expand the Variables section.
2. Select Add variable.

All projects in that group (and its subgroups) inherit the variable.

Instance CI/CD variables (admin only)

Instance variables are visible to every project and group on a self-hosted GitLab instance. You need administrator access to create them.

You can manage instance variables through the Admin area:

1. On the top bar, select Menu > Admin.
2. On the left sidebar, choose Settings > CI/CD and expand the Variables section.
3. Select Add variable and fill in the details.

You can also manage instance variables through the API.

Protecting and masking variables

When you create a variable (at any level), you will see two optional flags:

Protect variable: The variable is only available in pipelines that run on protected branches or protected tags. This prevents a random feature branch from accessing production secrets.

Mask variable: The variable’s value is hidden in job logs. If your script runs echo $SECRET_TOKEN, the output shows [masked] instead of the actual value.

For masked variables, the value has to meet certain requirements:

• It must be a single line.
• It must be at least 8 characters long.
• It can only contain characters from the Base64 alphabet (A-Z, a-z, 0-9, +, /, =), plus @, :, ., and ~.

If your value does not match these rules, the variable cannot be masked.

Environment scoping

You can also scope a variable to a specific deployment environment. By default, a variable has the environment scope * (all environments). But you might want a database password variable to only be available when deploying to production.

To set this, use the Environment scope dropdown when creating or editing a variable. This works for project, group, and instance variables. For a complete guide to using environment-scoped variables with deployments, see GitLab CI Environments and Review Apps.

Secrets management

GitLab has added built-in integration with external secret managers. Instead of copying secrets into GitLab’s CI/CD variable settings, you can fetch them directly from a vault at job runtime.

The secrets keyword works with:

• HashiCorp Vault: Authenticate using an id_tokens OIDC token and read secrets directly from Vault.
• AWS Secrets Manager: Retrieve secrets using OIDC authentication to AWS.
• Google Cloud Secret Manager: Access GCP secrets with Workload Identity Federation.

Here is a quick example with Vault:

job_using_vault:
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
    DATABASE_PASSWORD:
      vault: production/db/password@ops
      token: $VAULT_ID_TOKEN
  script:
    - connect-to-db -p "$DATABASE_PASSWORD"

This approach means your secrets live in one place (the vault) and are never stored in GitLab itself. Check the GitLab secrets management docs for setup details. If you want the broader identity-first design, the new Vault + Workload Identity Federation guide covers how to move from simple secret retrieval to short-lived, claim-bound access for CI and Kubernetes.

Predefined CI/CD variables

GitLab provides a long list of predefined variables you can use without declaring anything. GitLab sets their values automatically for each pipeline.

Some commonly used ones:

For the full list, see predefined CI/CD variables.

This example prints the current branch name:

print_branch:
  stage: pre
  script:
    - echo "$CI_COMMIT_REF_NAME"

Variable precedence

When the same variable name is defined in multiple places, GitLab applies a precedence order. Trigger variables and manual pipeline variables have the highest priority. Here is the general order, from highest to lowest:

1. Trigger variables (passed via the API)
2. Manual pipeline variables (set when running a pipeline manually)
3. Job-level variables (in .gitlab-ci.yml)
4. Global variables (top-level in .gitlab-ci.yml)
5. Project CI/CD variables
6. Group CI/CD variables
7. Instance CI/CD variables
8. Predefined variables

Knowing this order helps when you need to override a value for a specific job or pipeline run.

Conclusion

GitLab CI variables are straightforward once you understand the scope rules. Define non-sensitive config in your .gitlab-ci.yml, store secrets at the project or group level, and use environment scoping to keep production credentials out of non-production pipelines. If you are running self-hosted GitLab, the external secrets integration with Vault or AWS is worth setting up.

Check also other articles related to Gitlab:

Effective Cache Management with Maven Projects on Gitlab.

Pipeline to build Docker in Docker on Gitlab.

How to Autoscaling the Gitlab Runner.

Execute Terraform on Gitlab CI.

How to use Gitlab CI: Deploy to elastic beanstalk

GitLab CI Artifacts — store and pass files between pipeline stages.

Setup GitLab CI to pull from AWS ECR without long-lived credentials.

Effective Cache Management with GitLab CI — how to configure layer caching and cache keys that persist across pipeline runs.

Terraform and Ansible: The Integration That Actually Works — pull vs push models, variable passing between tools, and the bootstrap patterns that don’t silently fail.