Variables & Secrets

CI/CD variables are dynamic values that are injected into your pipeline at runtime. They're the primary mechanism for configuring pipelines without hardcoding values, and they're absolutely essential for handling secrets like API keys, database passwords, and TLS certificates securely. Every time a job runs, GitLab assembles a set of environment variables from multiple sources and makes them available to your scripts.

Understanding variables is critical because they control almost every aspect of a pipeline's behavior. They determine which Docker registry you push to, which Kubernetes namespace you deploy into, what API endpoints your tests hit, and which credentials your deployment scripts use. A misconfigured variable can break a pipeline, leak a secret, or deploy code to the wrong environment. Getting them right is fundamental to reliable, secure CI/CD.

GitLab provides several types of variables, each with different scoping and security properties. Predefined variables are set by GitLab automatically. Custom variables are defined by you in the .gitlab-ci.yml file or in the GitLab UI. Protected variables are only available on protected branches. Masked variables have their values hidden in job logs. Understanding the distinction between these types is essential for building secure pipelines.

GitLab provides dozens of predefined variables that are automatically available in every pipeline. These variables give you access to information about the commit, branch, pipeline, project, and environment. They're essential for writing dynamic pipelines that adapt to the context in which they run — for example, using the commit SHA as an image tag, or deploying to different environments based on the branch name.

Predefined variables are read-only — you can't overwrite them. They follow a consistent naming convention: they all start with CI_ and use uppercase with underscores. Learning the most common ones will save you significant time and make your pipelines more robust.

Custom variables can be defined directly in your .gitlab-ci.yml file. This is the most common way to define non-sensitive configuration values that don't need to be hidden — things like application names, default versions, or feature flags. Variables defined this way are visible in the repository, so they must never contain secrets.

Variables can be defined at three scopes: pipeline scope (top-level variables keyword), job scope (inside a specific job), and global scope (via default:variables). Job-scoped variables override pipeline-scoped variables with the same name, which gives you fine-grained control over each job's configuration.

Variables can also reference other variables — GitLab expands them at runtime. This lets you build complex values from simple pieces, like combining a registry URL with an image name and version. Just be careful about recursive references, which GitLab will reject.

Masked variables are the most basic form of secret protection in GitLab. When you mark a variable as masked, GitLab replaces its value with [MASKED] in job logs. This prevents accidental disclosure of secrets through echo statements, error messages, or debug output. It's not a perfect security mechanism — it's a safety net — but it's essential for any value that should never appear in a log.

Masked variables have specific requirements that you must satisfy for the masking to work. The value must be a single line, at least 8 characters long, and must not contain whitespace or certain special characters. These restrictions exist because GitLab uses a pattern-matching approach to mask — it scans job logs for the exact value and replaces matches. If the value is too short or contains unusual characters, the masking might fail or be unreliable.

To configure a masked variable, go to your project's Settings → CI/CD → Variables, click "Add variable," and check the "Masked" option. Alternatively, you can use the GitLab API to create masked variables programmatically. Remember: masking only protects values in job logs. It doesn't encrypt them, doesn't hide them from project maintainers, and doesn't prevent them from being exfiltrated by malicious code in a pipeline.

Protected variables take secret protection to the next level. A protected variable is only available to pipelines running on protected branches or protected tags. This means you can safely store production credentials in a protected variable, knowing that feature branches and merge requests can't access them. It's a fundamental security control for production CI/CD.

The reasoning behind protected variables is straightforward: feature branches are where developers experiment, where unreviewed code runs, and where malicious code could be introduced. If a feature branch could access production database credentials, a compromised developer account could exfiltrate them simply by pushing code that echoes the secret. By marking production secrets as protected, you create a hard boundary: only code that has passed review and merged to a protected branch can access these secrets.

Protected variables work together with protected branches. By default, a new GitLab project has a single protected branch — main (or master, depending on GitLab version). You can add additional protected branches (like release/*) and protected tags. Any branch or tag marked as protected will have access to protected variables; any other branch will see the variable as undefined.

File variables solve a problem that masked variables can't: multi-line secrets. Things like TLS certificates, SSH private keys, JSON service account credentials, and kubeconfig files are inherently multi-line. They can't be masked (masking requires single-line values), and passing them as environment variables is awkward and error-prone. File variables solve this by storing the value as a file on the runner and exposing the file's path through the variable.

When you create a file variable, GitLab writes the value to a temporary file on the runner and sets the environment variable to that file's path. Your script then reads the file with standard file operations. This is elegant because it works naturally with tools that expect file paths — kubectl --kubeconfig=$KUBECONFIG, docker login --password-stdin < $DOCKER_PASSWORD_FILE, and similar patterns.

File variables are perfect for anything that is naturally a file: certificates, keys, configuration files, JSON credentials, and archives. They're also a security best practice for SSH keys — storing an SSH key in a file variable and using it via $SSH_KEY_FILE avoids the common pitfall of echoing the key to disk with echo "$SSH_KEY" > key, which can leak the key into logs.