Getting started with GitLab: Working with CI/CD variables

Welcome to our "Getting started with GitLab" series, where we help newcomers get familiar with the GitLab DevSecOps platform.

In an earlier article, we explored GitLab CI/CD. Now, let's dive deeper into the world of CI/CD variables and unlock their full potential.

What are CI/CD variables?

CI/CD variables are dynamic key-value pairs that you can define at different levels within your GitLab environment (e.g., project, group, or instance). These variables act as placeholders for values that you can use in your .gitlab-ci.yml file to customize your pipelines, securely store sensitive information, and make your CI/CD configuration more maintainable.

Why are CI/CD variables important?

CI/CD variables offer numerous benefits:

• Flexibility - Easily adapt your pipelines to different environments, configurations, or deployment targets without modifying your core CI/CD script.

• Security - Securely store sensitive information like API keys, passwords, and tokens, preventing them from being exposed directly in your code.

• Maintainability - Keep your CI/CD configuration clean and organized by centralizing values in variables, making updates and modifications easier.

• Reusability - Define variables once and reuse them across multiple projects, promoting consistency and reducing duplication.

Scopes of CI/CD variables: Project, group, and instance

GitLab allows you to define CI/CD variables with different scopes, controlling their visibility and accessibility:

• Project-level variables - These variables are specific to a single project and are ideal for storing project-specific settings, such as:

  • Deployment URLs: Define different URLs for staging and production environments.
  • Database credentials: Store database connection details for testing or deployment.
  • Feature flags: Enable or disable features during different stages of your pipeline.
  • Example: You have a project called "MyWebApp" and want to store the production deployment URL. You create a project-level variable named DPROD_DEPLOY_URL with the value https://mywebapp.com.

• Group-level variables - These variables are shared across all projects within a GitLab group. They are useful for settings that are common to multiple projects, such as:

  • API keys for shared services: Store API keys for services like AWS, Google Cloud, or Docker Hub that are used by multiple projects within the group.
  • Global configuration settings: Define common configuration parameters that apply to all projects in the group.
  • Example: You have a group called "Web Apps" and want to store an API key for Docker Hub. You create a group-level variable named DOCKER_HUB_API_KEY with the corresponding API key value.

• Instance-level variables - These variables are available to all projects on a GitLab instance. They are typically used for global settings that apply across an entire organization such as:

  • Default runner registration token: Provide a default token for registering new runners.
  • License information: Store license keys for GitLab features or third-party tools.
  • Global environment settings: Define environment variables that should be available to all projects.
  • Example: You want to set a default Docker image for all projects on your GitLab instance. You create an instance-level variable named DEFAULT_DOCKER_IMAGE with the value ubuntu:latest.

Defining CI/CD variables

To define a CI/CD variable:

1. Click on the Settings > CI/CD buttons for your project, group, or instance.

2. Go to the Variables section.

3. Click Add variable.

4. Enter the key (e.g., API_KEY) and value.

5. Optionally, check the Protect variable box for sensitive information. This ensures that the variable is only available to pipelines running on protected branches or tags.

6. Optionally, check the Mask variable box to hide the variable's value from job logs, preventing accidental exposure.

7. Click Save variable.

Using CI/CD variables

To use a CI/CD variable in your .gitlab-ci.yml file, simply prefix the variable name with $:

deploy_job:
  script:
    - echo "Deploying to production..."
    - curl -H "Authorization: Bearer $API_KEY" https://api.example.com/deploy

Predefined CI/CD variables

GitLab provides a set of predefined CI/CD variables that you can use in your pipelines. These variables provide information about the current pipeline, job, project, and more.

Some commonly used predefined variables include:

• $CI_COMMIT_SHA: The commit SHA of the current pipeline.

• $CI_PROJECT_DIR: The directory where the project is cloned.

• $CI_PIPELINE_ID: The ID of the current pipeline.

• $CI_ENVIRONMENT_NAME: The name of the environment being deployed to (if applicable).

Best practices

• Securely manage sensitive variables: Use protected and masked variables for API keys, passwords, and other sensitive information.

• Avoid hardcoding values: Use variables to store configuration values, making your pipelines more flexible and maintainable.

• Organize your variables: Use descriptive names and group related variables together for better organization.

• Use the appropriate scope: Choose the correct scope (project, group, or instance) for your variables based on their intended use and visibility.

Unlock the power of variables

CI/CD variables are a powerful tool for customizing and securing your GitLab pipelines. By mastering variables and understanding their different scopes, you can create more flexible, maintainable, and efficient workflows.

We hope you found it helpful and are now well-equipped to leverage the power of GitLab for your development projects.

Get started with CI/CD variables today with a free trial of GitLab Ultimate with Duo Enterprise.

"Getting Started with GitLab" series

Read more articles in our "Getting Started with GitLab" series:

• How to manage users

• How to import your projects to GitLab

• Mastering project management

• Automating Agile workflows with the gitlab-triage gem

• Understanding CI/CD