The Ultimate Manual for GitLab CI/CD Variables

GitLab gives us a lot of flexibility to automate repetitive tasks and track changes and actions when building applications and executing scripts that deploy the applications for us. Regardless of the project complexity, there is one thing that needs to be done: declaring variables.

Why? Declaring variables lets you control the workflow of your scripts and define configurations from within your environment. 

What is GitLab?

GitLab is a repository hosting manager tool developed by GitLab Inc designed to create streamlined software workflows to accelerate the software development process. It provides users with a variety of management tools that can help them streamline collaborative workflow to complete the software development cycle. Developers can also use the tool to import the repository from BitBucket, Google Code, and other similar platforms.

Here is a quick at-a-glance rundown of GitLab features:

• Open-source community edition repository management platform
• Provides useful tools like time tracking and issue tracker, group milestones, and several others for effective software development
• Easy repository maintenance on a server
• Spontaneous UI and authentication features
• Enhanced user permission and branched protection

What are GitLab CI/CD Variables Anyway?

GitLab CI/CD (continuous integration/continuous delivery) variables are environmental variables that are available globally for the whole project. You can use them to: 

• Control and execute jobs in pipelines
• Store values to be consumed by the script
• Prevent repetition of the same value for all branches
• Avoid hard-coding values in your .gitlab-ci.yml file

Understanding the Relationship Between Variables and GitLab Environments

Software development, as a process, comprises various stages to test a product before rolling it out to users. On the other hand, environments come in handy to define what the stages look like and can differ between teams and organizations.

In between these two terms comes variables, which are data values that are subject to change as a result of user interaction with your product. For instance, their preference, gender, or age—or any other input—can determine their next step in the product task flow.

You may have also heard of environment variables. These refer to variables defined in a given environment but outside the application. GitLab environment variables enable developers to configure values in their code. Through them, you can ensure your code stays flexible and modify an application deployed to a certain environment without making any changes to the code.

You can also run tests and integrate third-party services by charging a configuration environment variable outside the application. 

How GitLab CI/CD Variables Work

In GitLab, CI/CD variables are used to customize jobs by defining and storing values. Depending on the circumstance and requirements, you can use predefined CI/CD variables or define custom:

• Variables .gitlab-ci.yml file
• Project CI/CD variables
• Group CI/CD variables
• Instance C/CD variables

Let’s discuss these terms in more detail below.

Predefined CI/CD Variables

GitLab CI/CD has a default set of predefined CI/CD variables. You can use them in pipeline configuration and job scripts. For instance, you can use predefined CI/CD variables in your .gitlab-ci.yml file without declaring them beforehand.

Here’s a sample to show you how to output the branch team by using the CI_COMMIT_REF_NAME predefined variable:

ob:

  stage: pre

  script:

    – echo “$CI_COMMIT_REF_NAME”

Custom CI/CD Variables

You can create custom CI/CD variables in three ways:

• For a project (in the project’s .gitlab-ci.yml file, in the project’s settings, and with the API)
• For all projects in a group in the group’s setting
• For all projects in a GitLab instance in the instance’s settings

Let’s understand how you can create variables in the .gitlab-ci.yml file.

Specify the variable and value with the variables keyword. Place the keyword variable on the top level of the .gitlab-ci.yml file. Alternatively, you can place it in a job and on a stage level.

You can define the variable at the top level for certain cases that can be used by any jobs. But if it’s already described in a job, only that job can use the variable. Another option is to override variable values manually for a specific pipeline or have them pre-filled in manual pipelines. 

There are two types of variables: File and Variable.

Variable names are limited by the shell you use to execute scripts, with each shell having its own set of reserved variable names. Your responsibility is to ensure each variable is properly defined for the scope you want to use it for. 

Also, pipelines from forked projects have no access to CI/CD variables in the parent project. This is a default setting. But if you run a merger request pipeline in the parent project for a merger request from a forked project, all variables will become available to the pipeline.

Project CI/CD Variables

Creating CI/CD variables for a project’s settings is also possible, but only project members with Maintainer role privileges can create or edit these variables.

To configure a CI/CD variable secret, you will have to set it in the project settings and not in the .gitlab-ci.yml file. When using these variables, you don’t have to hard code values. They can be defined by going to Settings > CI/CD> Variables.

Group CI/CD Variables

Creating a group CI/CD variable is a prerequisite to creating a CI/CD variable and making it available to all projects in a group. Using group variables also makes sense to put in passwords, enter credentials, and maintain SSH public/private keys.

To create a group CI/CD variable, open Settings followed by CI/CD in your group.

Instance CI/CD Variables

If you want to create a CI/CD variable and make it visible to all projects and groups in a whole GitLab instance, you need to insert an instance CI/CD variable, which is only possible when you are the administrator for the instance.

To go about this, you have two options:

• Go directly to this address: https://<your-gitlab>/admin/application_settings/ci_cd
• Specify instance variables via the UI or API.

To create an instance variable, follow the steps below:

1. On the top bar, click on Menu followed by Admin.
2. On the left sidebar, select Settings. Click on CI/CD and then open the Variables section.
3. Select the Add Variable button, and type in the Key and Value details. 

Here, you’ll also notice two flags that are optional but can be critical for certain scenarios. They are:

Protect variable is the variable available in pipelines that run solely on protected branches or tags.

Mask variable refers to the variable value masked in logs output from the jobs. Also, you can only save variables that match the following requirements:

• The value of the variable must be a single line
• The value of the variable must be eight characters or greater, comprising characters from the Base64 alphabet, the @ and : characters, the . character, and the ~ character 

How to Use Variables in Other Variables

Variables can be used to define new variables as well. Here’s the code to do it:

variables:

 GLOBAL_VAR: “This variable is visible for all jobs.”

job_1:

  variables:

    JOB_LOCAL_VAR: “Only job_1 can use this variable’s value.”

  script:

    – echo “$GLOBAL_VAR” and “$JOB_LOCAL_VAR.”

Helpful Posts to Navigate GitLab

Now that you’re familiar with GitLab CI/CD, we recommend checking out other GitLab-related posts to help you understand the platform even better.

If your workflow includes Jira, take a look at our The Ultimate Manual to GitLab Jira Integration piece. Or if you want to learn more about SSH key setups, our The Ultimate Manual for GitLab SSH Key Setup post covers the feature in more detail.

Conclusion

GitLab’s CI/CD variables implementation makes pipeline configuration more powerful and flexible than ever. One of the biggest problems when defining variables is identifying all the places where a value should be located.

Typically, you can place as many values as you want at the group level, saving yourself the time and effort required in repeating this within projects. You can always override a variable later in specific projects that need a different value. 

Besides this, self-hosted GitLab admins typically use instance variables to expose common shared values. But keep in mind this may lead to unintentional information exposure if you don’t manage it properly.