Gitlab CI Variables [Complete Guide]

Gitlab is an excellent tool for building applications and executing scripts that deploy the applications for us—giving us a lot of power to automate tedious tasks and keep tracking all changes and actions.

Regardless of the project complexity, declaring variables is always needed. Maybe to control the workflow of our scripts or define the configuration from our environment.

We will see how Gitlab CI variables work and how to define them because we will discover that there are different ways to declare them, and because of that, the scope of those variables will change too. So, it’s crucial to know which approach to choose.

If you are trying to change the workflow of your pipeline based on variables. For example, for a merge request, or for a specific branch, you need to customize your pipeline to perform different approaches, you can check the Gitlab Rules, to achieve that goal.

GitLab CI Variables

CI/CD variables are environment variables, and it’s available globally for the whole project. The main goal for them:

• The most important: avoid hard-coding values in your .gitlab-ci.yml file.
• Control the execution of jobs and pipelines.
• Store values to be consumed by the scripts.
• Avoid repeating the same value for all branches. So, if we need to change it, we don’t need to change all branches.

Also, we can use predefined CI/CD variables or define custom:

So besides, declare the variables in the .gitlab-ci.yml file, we can also create them using those approaches below:

• Project CI/CD variables.
• Group CI/CD variables.
• Instance CI/CD variables.

Let’s discuss them:

Create your CI/CD variable in the .gitlab-ci.yml file

To create your variable in the .gitlab-ci.yml file, specify the variable and value with the variables keyword.

You can place the keyword variable on the top level of the .gitlab-ci.yml file or in a job and on a stage level.

There are cases where we can define the variable at the top level, this variable scope is globally available, and any jobs can use it. However, if it’s described in a job, only that job can use it.

See this example:

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."

Variables stored in the .gitlab-ci.yml file should store exclusively non-sensitive project configuration, like a JAVA_HOME or JDBC_URL variable. These variables are noticeable in the repository. Store sensitive variables carry secrets, keys, and so on in CI/CD variables for each project (see more details below).

Variables stored in the .gitlab-ci.yml file are also available in service containers.

Also, it’s possible to override variable values manually for a particular pipeline or have them prefilled in manual pipelines.

There are two kinds of variables: File or Variable.

The shell limits variable names the runner uses to perform scripts. Each shell has its private set of reserved variable names.

Be sure every variable is defined for the scope you want to use it in.

The standard, pipelines from forked projects can’t reach CI/CD variables in the parent project. 

However, there is a specific scenario where all variables become available: When you perform a fork’s merge request in the parent project.

How to use variables in other variables

You can use variables to define new variables. See below:

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."

---

Take some minutes, and visit:

---

Project CI/CD variables

You can create CI/CD variables for a project’s settings. However, only project members with the Maintainer role can create or edit project CI/CD variables (An excellent approach to protect them). To configure a CI/CD variable secret, set it in the project settings, not the .gitlab-ci.yml file.

To create or edit variables in the project, go to the settings from that project:

1. On your project’s Settings > CI/CD, then expand the Variables section.

Group CI/CD variables

To create a CI/CD variable and make it available to all projects in a group, set a group CI/CD variable.

• Utilize group variables to put passwords, SSH public/private keys, and credentials.

To create a group variable, follow the steps:

1. In your group, go to Settings > CI/CD.

Define a Global Variable for all projects – Instance CI/CD variables

To create a CI/CD variable visible to all projects and groups in a GitLab instance, insert an instance CI/CD variable. You must be the Administrator.

You can go directly to this address:

1. https://<your-gitlab>/admin/application_settings/ci_cd

or

You can specify instance variables via the UI or API.

To create an instance variable:

1. On the top bar, select Menu > Admin.
2. On the left sidebar, choose Settings > CI/CD and open the Variables section.
3. Choose the Add variable button, and type in the details:

• Key
• Value

Also, you will notice that we have two flags that are optional but very important for some scenarios.

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

Mask variable: the variable’s value will always be masked in logs output from the jobs. 

For Mask variables, you can only save variables that match with requirements below:

The value of the variable must:

• Be a single line.
• Be eight characters or greater, consisting only of:
  • Characters from the Base64 alphabet (RFC4648).
  • The @ and : characters
  • The . character
  • The ~ character

What are Predefined CI/CD variables on Gitlab?

The GitLab CI/CD already gives us a set of predefined CI/CD variables that you can reuse in your pipelines and job scripts.

To check the complete list, check here: predefined CI/CD variables. Also, we can use Gitlab Rules, with variables.

How to use the predefined CI/CD variables.

You can use the predefined variables on your .gitlab-ci.yml, and the best part is that you don’t need to declare them. Instead, Gitlab automatically updates the values from those variables.

This sample shows how to output the branch name by using the CI_COMMIT_REF_NAME predefined variable:

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

Conclusion

Gitlab CI Variables are easy to use and declare. But we need to be aware of which approach we need to adopt to achieve our project’s scope.

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