Course contentsShow
← Cloud and Infrastructure
Lesson 1763 of 2,98936. GitLab CI/CDFree lesson

Custom CI/CD Variables and Inheritance

Configure variable precedence, masking, protection, and inheritance across project, group, and instance levels.

Custom CI/CD Variables and Inheritance

What you'll learn: How to control variable precedence and scope across GitLab's three-tier hierarchy—instance, group, and project levels.

Understanding Variable Scope and Inheritance

GitLab CI/CD variables can be defined at three levels, each inheriting from the level above:

  • Instance-level: Set by administrators for all projects (lowest precedence)
  • Group-level: Applied to all projects within a group
  • Project-level: Specific to one project (highest precedence)

Variables cascade downward like CSS styles—a project variable overrides a group variable, which overrides an instance variable. This hierarchy lets you set organization-wide defaults while allowing teams to customize as needed.

Variable Protection and Masking

Protected variables only expose to pipelines running on protected branches (like main or production). This prevents sensitive credentials from leaking in feature branch pipelines.

Masked variables hide their values in job logs, replacing them with [masked]. Use masking for tokens, passwords, or API keys. Requirements: must be a single line, at least 8 characters, and contain no special characters that break masking patterns.

Variable Precedence Order (Highest to Lowest)

  1. Pipeline-specific variables (trigger API, manual run)
  2. Project-level variables
  3. Group-level variables
  4. Instance-level variables
  5. .gitlab-ci.yml file definitions
  6. GitLab predefined variables

When the same variable name exists at multiple levels, the highest precedence wins. This pattern lets you override defaults contextually—for example, using different API endpoints per project while sharing common credentials at the group level.

Key Takeaway: GitLab's variable inheritance system follows a clear precedence hierarchy from instance → group → project → pipeline, with protection and masking options ensuring sensitive data stays secure across your CI/CD landscape.