DevOps as Craft

DevOps and DeSecOps in Romania - descoperă cum să integrezi securitatea în procesul de dezvoltare a aplicațiilor. Practica, tendințe, și instrumente.

How to Create Variables in GitLab CI: The Complete Guide

by ·

GitLab CI variables are like special notes you can use in your CI/CD pipeline. They help you store important information that you might need later, like passwords or settings. In this guide, we will learn everything about GitLab CI variables, from what they are to how to use them effectively.

Key Takeaways

  • GitLab CI variables store important information for your CI/CD pipelines.
  • You can set variables at the instance, group, or project level.
  • Variables can be used in scripts to make pipelines more flexible.
  • Masking and protecting variables keep sensitive information safe.
  • Troubleshooting helps fix common issues with variables.

Understanding GitLab CI Variables

person using MacBook

What are GitLab CI Variables?

GitLab CI variables are like environment variables that you can use in your CI/CD pipelines. They help you control and execute jobs, store values, and avoid hard-coding. These variables make your pipelines more flexible and easier to manage.

Types of GitLab CI Variables

There are several types of GitLab CI variables:

  • Predefined Variables: These are built-in and always available. They include details about commits, branches, and merge requests.
  • Custom Variables: You can define these yourself at the instance, group, project, or pipeline level.
  • Protected Variables: These are only available in pipelines running on protected branches or tags.
  • Masked Variables: These variables have their values hidden in job logs for security.

Why Use GitLab CI Variables?

Using GitLab CI variables can make your life easier in many ways:

  • Control Job Behavior: You can use variables to control how jobs run in your pipeline.
  • Store Reusable Values: Save values that you need to use in multiple places, like API keys or configuration settings.
  • Avoid Hard-Coding: Keep your .gitlab-ci.yml file clean and flexible by using variables instead of hard-coded values.

GitLab Ultimate integrates security and compliance into the DevOps lifecycle, automating policies and scanning throughout development. This makes managing variables even more crucial for a secure software development process.

In summary, GitLab CI variables are essential for making your CI/CD pipelines more efficient and secure. They offer flexibility, reusability, and better control over your jobs and scripts.

Setting Up Instance Variables

Accessing the CI/CD Settings

To set up instance variables, 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 these steps:

  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.

Adding a New Instance Variable

When adding a new instance variable, you need to provide a unique Key and a Value. The Key is how you’ll reference the variable within your pipeline and its scripts. Make sure the name you choose is compatible with the shell that will run your job. All variables should be a valid string containing only alphanumeric characters and underscores.

Next, set the value of your variable. When the "Type" dropdown is left at "Variable," this value will be injected as-is each time you reference the variable in your pipeline. Changing the type to "File" will inject the value as a temporary file in your build environment; the value of the environment variable will be the path to that temporary file. This can be a safer way to inject sensitive data if your application is prepared to read the final value from the specified file.

Once you’re done, click the green Add variable button to complete the process. You can now reference your variable in pipelines that execute within the scope you defined it in. For a project variable, it’ll be defined for pipelines inside that project, whereas instance-level variables will be available to every pipeline on your GitLab server.

Optional Flags for Instance Variables

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

  • Protect variable: The variable is available in pipelines that run solely on protected branches or tags.
  • Mask variable: The variable value is 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.

Pro Tip: Masking variables is a great way to enhance security by ensuring sensitive data doesn’t appear in your job logs.

By following these steps, you can easily set up instance variables in GitLab CI/CD, making your pipelines more flexible and secure.

Creating Project-Level Variables

Navigating to Project Settings

To start, you need to access your project’s settings. On the left sidebar, select Search or go directly to your project. Once there, click on Settings and then CI/CD. This is where you can manage all your CI/CD variables.

Defining Variables in .gitlab-ci.yml

You can define variables directly in your .gitlab-ci.yml file. This method is straightforward and keeps your variables close to your pipeline configuration. However, be cautious as this can expose sensitive information if not handled properly.

Using the GitLab UI to Add Variables

  1. Go to your project and select Settings > CI/CD.
  2. Expand the Variables section.
  3. Click on Add variable and fill in the details:
    • Key: Must be one line, with no spaces, using only letters, numbers, or underscores.
    • Value: No limitations.
    • Type: Choose between Variable (default) or File.
    • Environment scope: Optional. All (default), a specific environment, or a wildcard environment scope.
    • Protect variable: Optional. If selected, the variable is only available in pipelines that run on protected branches or tags.
    • Mask variable: Optional. If selected, the variable’s value is masked in job logs.

Pro Tip: Use protected variables for sensitive data like deployment keys to reduce the risk of accidental exposure.

After adding your variables, you can reference them in your pipeline configuration or job scripts. This makes your pipelines more flexible and secure.

Group-Level Variables Explained

Why Use Group-Level Variables?

Group-level variables are super handy when you need to share settings across multiple projects within a group. They help you keep things consistent and save time by not having to set the same variable in each project. This is especially useful for large teams working on several projects that need the same configurations.

Steps to Create Group Variables

Creating group variables is a breeze. Just follow these steps:

  1. Navigate to your group in GitLab.
  2. Go to Settings > CI/CD.
  3. Expand the Variables section.
  4. Click the Add Variable button.
  5. Fill in the Key and Value fields.
  6. Optionally, set the environment scope and other flags.
  7. Click Add Variable to save.

That’s it! Your group variable is now ready to use in any project within the group.

Managing Group Variables

Managing group variables is straightforward. You can edit or delete them anytime by going back to the Settings > CI/CD > Variables section of your group. Click the pencil icon next to any variable to edit it. You can also delete variables that are no longer needed.

The group variables that are available in a project are listed in the project’s settings > CI/CD > variables section. Variables from subgroups are recursively inherited.

Remember, you can also protect or mask variables to enhance security. Protecting a variable means it will only be available in pipelines running against protected branches or tags. Masking a variable hides its value in job logs, which is great for sensitive data like API keys.

By using group-level variables, you can streamline your CI/CD processes and ensure consistency across all your projects.

Using Variables in Your Pipelines

Referencing Variables in Scripts

Variables in GitLab CI are key-value pairs that you can use in your scripts. To reference a variable, use the $ symbol followed by the variable name. For example, if you have a variable named MY_VAR, you can use it in your script like this:

script:
  - echo "$MY_VAR"

This will print the value of MY_VAR to the console. Remember to always use the correct syntax to avoid errors in your pipeline.

Variable Expansion Mechanisms

GitLab CI supports variable expansion, which means you can use variables within other variables. For instance, if you have a variable BASE_URL and another variable API_ENDPOINT, you can combine them like this:

variables:
  BASE_URL: "https://api.example.com"
  API_ENDPOINT: "$BASE_URL/v1/resource"

This will set API_ENDPOINT to https://api.example.com/v1/resource. Variable expansion helps in creating dynamic and flexible pipelines.

Common Use Cases for Variables

Variables are incredibly useful in various scenarios. Here are some common use cases:

  • Environment Configuration: Set different variables for different environments like development, staging, and production.
  • Sensitive Data: Store sensitive information like API keys and passwords securely.
  • Dynamic Values: Use variables to create dynamic values that change based on the pipeline’s context.

Using variables effectively can make your pipelines more secure and easier to manage.

By mastering the use of variables, you can create more efficient and flexible CI/CD pipelines in GitLab.

Advanced Variable Management

Masking and Protecting Variables

Managing sensitive data in your pipelines is crucial. GitLab CI offers two key features: masking and protecting variables. Masking hides the variable’s value in job logs, ensuring sensitive information like tokens don’t get exposed. Protecting variables restricts their use to protected branches or tags, adding an extra layer of security.

To mask a variable, simply check the ‘Mask variable’ option when adding or editing a variable. This will filter out the variable’s value from job logs. Note that masking works best with values that follow specific formats, like Base64-encoded data.

Protected variables are useful for deployment keys or other sensitive values that should only be used in specific pipelines. By marking a variable as protected, you limit its exposure to only the necessary jobs, reducing the risk of accidental leaks.

Overriding Variables

Sometimes, you might need to override a variable’s value. GitLab CI allows you to define variables with the same name in different scopes, but the values can overwrite each other based on a specific order of precedence.

Here’s the order of precedence for variables, from highest to lowest:

  1. Scan Execution Policies variables
  2. Pipeline variables (e.g., downstream pipelines, trigger variables)
  3. Project variables
  4. Group variables
  5. Instance variables
  6. Variables from dotenv reports
  7. Job-defined variables in .gitlab-ci.yml
  8. Globally defined variables in .gitlab-ci.yml
  9. Deployment variables
  10. Predefined variables

Understanding this hierarchy helps you manage and troubleshoot variable values effectively.

Using Variables in Other Variables

GitLab CI allows you to reference one variable within another, making your configurations more dynamic. This is known as variable expansion. By default, variables with a $ character are treated as references to other variables.

For example, if you have a variable BASE_URL set to https://example.com, you can create another variable API_ENDPOINT with the value $BASE_URL/api. This way, API_ENDPOINT will expand to https://example.com/api during runtime.

If you need to treat a variable with a $ character as a raw string, you can disable variable expansion. To do this, go to Settings > CI/CD, expand Variables, and edit the variable. Uncheck the ‘Expand variable’ option and save your changes.

Using variables within other variables can greatly simplify your pipeline configurations and make them more maintainable. Just be cautious with the order of precedence to avoid unexpected behaviors.

Troubleshooting Variable Issues

Common Errors and Fixes

When working with GitLab CI variables, you might encounter some common errors. One frequent issue is undefined variables. This usually happens when a variable is not set in the expected scope. Double-check your variable definitions and ensure they are set at the correct level, whether it’s instance, group, or project.

Another common problem is syntax errors in your .gitlab-ci.yml file. YAML is very particular about indentation and formatting. Make sure your file follows the correct structure to avoid these issues.

Debugging Variable Problems

To debug variable issues, you can list all available variables in your script. Use the export command in Bash or dir env: in PowerShell. This will show the values of all variables, but be cautious as this can expose sensitive information. Masked variables will display as [masked].

For example, in Bash:

job_name:
  script:
    - export

This will output all environment variables available to the job, helping you identify any missing or incorrectly set variables.

Best Practices for Variable Management

Managing variables effectively can save you a lot of headaches. Here are some best practices:

  • Use descriptive names: Make your variable names clear and descriptive to avoid confusion.
  • Scope appropriately: Set variables at the correct level to ensure they are available where needed.
  • Protect sensitive variables: Use masking and protection features to keep sensitive information secure.

By following these guidelines, you can minimize issues and make your CI/CD pipelines more robust.

Having trouble with your variables? Don’t worry, we’ve got you covered! Our latest guide on troubleshooting variable issues is here to help you solve those pesky problems quickly and easily. For more tips and detailed solutions, be sure to visit our website.

Frequently Asked Questions

What are GitLab CI variables?

GitLab CI variables are key-value pairs used in your CI/CD pipelines. They help manage configurations, secrets, and other data without hardcoding them into your scripts.

How do I add an instance variable in GitLab?

To add an instance variable, go to Menu > Admin. Then, navigate to Settings > CI/CD and open the Variables section. Click on ‘Add Variable’ and fill in the Key and Value.

Why should I use GitLab CI variables?

Using GitLab CI variables helps keep your code clean and secure. They allow you to manage sensitive information and configuration settings without hardcoding them, making your pipelines more flexible.

Can I use variables within other variables in GitLab CI?

Yes, you can use variables within other variables. For example, you can define a global variable and use it inside job-specific variables to create dynamic configurations.

What are the optional flags for instance variables?

There are two optional flags for instance variables: ‘Protect variable’ and ‘Mask variable.’ Protect variable limits its use to protected branches or tags. Mask variable hides its value in job logs.

How do I troubleshoot variable issues in GitLab CI?

To troubleshoot variable issues, check for common errors like typos in variable names or missing values. Use debug logging to get more details and follow best practices for variable management to avoid problems.

Tags:

You may also like...