CI/CD Variables, Inputs, Secrets, File Variables, Masking, Protection, and Scope: Configuration, Design Choices, and Tradeoffs

1. Design principle: choose the narrowest mechanism that matches the data

The easiest pipeline to write is often the hardest to govern: put everything in variables, let every job inherit it, and override values when necessary. Production CI should do the opposite. First classify the data as configuration parameter, runtime setting, or secret; then choose the smallest scope and shortest lifetime that works.

2. Typed input versus variable

Pipeline inputs are recommended over pipeline variables for run-time parameters. If inputs meet the need, restrict or disable pipeline variables so a high-precedence untyped value cannot silently override the pipeline contract.

3. Project versus group versus instance scope

Centralization reduces duplication only when the trust domain is actually shared. Do not put a production credential at group scope merely because several projects happen to deploy to the same platform.

4. Protected ref and environment scope answer different questions

Protected asks: “Is this pipeline running on an approved protected branch or tag?” Environment scope asks: “Is this job targeting an environment whose name matches the scope?” A production deployment may need both controls, plus a protected environment and appropriate runner isolation in later chapters.

Current GitLab supports environment scope on project variables. Environment scope for group variables is Premium/Ultimate. Do not use environment-scoped variables inside rules or include logic because those values may not be available when pipeline configuration is validated.

5. Broad inheritance versus explicit duplication

A shared group variable can simplify fleet-wide configuration, but it also makes every inheriting project's pipeline code a potential consumer. Prefer group scope for values that genuinely belong to the group trust domain. Prefer project scope when ownership, rotation cadence, or incident response differs by application.

If the same key exists at group and project levels, project wins. This override ability is useful for migration, but can also hide stale group configuration. Inventory all same-name definitions during incidents and deprecations.

6. Variable expansion: opt in only when it buys something

UI variable expansion is disabled by default in GitLab 18.6 and later. This is a safer default because values containing $ are treated literally unless expansion is intentionally enabled. Masked/hidden variables cannot use variable-reference expansion.

Prefer explicit composition in application configuration or scripts with well-quoted variables rather than nested secret expansion. Complex chains make precedence and incident response harder to reason about.

7. Pipeline variables: treat high precedence as delegated authority

Allowing a user to set pipeline variables is allowing that user to override project, group, instance, and YAML values. GitLab therefore provides a project setting for the minimum role allowed to use pipeline variables, including no_one_allowed. Use the narrowest role compatible with your workflow, and prefer inputs for ordinary operator parameters.

8. Stored variable versus external secret manager

9. OIDC separates identity from a long-lived credential

OIDC ID tokens are Free across GitLab.com, Self-Managed, and Dedicated. GitLab signs a short-lived token for the job. The external provider validates its audience and claims, applies its own trust policy, and returns temporary access.

Provider policy should bind stable and narrow claims such as project/namespace identity and allowed ref/environment context. Treat the ID token itself as a credential: never print it, add it to artifacts, or pass it to services outside its intended audience.

10. Built-in external-secret integrations and GitLab Secrets Manager

GitLab's secrets integrations for Vault, Google Cloud Secret Manager, Azure Key Vault, and AWS Secrets Manager are Premium/Ultimate. They use ID-token-based authentication and explicitly requested secrets. The course does not require them.

GitLab Secrets Manager is fast-moving and remains optional here. GitLab's 19.3 release announcement moved the GitLab.com offering into Limited Availability as a paid add-on through GitLab Credits, while the current Self-Managed OpenBao administration documentation still labels that offering Beta and requires GitLab Runner 19.0+ for CI/CD consumption. Re-check offering, status, billing, and Runner requirements before production adoption. The stable design lesson is broader: secret retrieval should be explicit, least-privilege, and preferably short-lived.

11. Worked decision table

12. Governance checklist before adding a value

• What classification is the data: public configuration, sensitive configuration, or secret?
• Which jobs need it? Which jobs must never receive it?
• Can a typed input replace a high-precedence pipeline variable?
• Can OIDC/federation replace a stored long-lived credential?
• What is the narrowest project/group/environment/ref scope?
• Who can change pipeline code that receives the value?
• Which runners execute those jobs and what else can they access?
• How will the value be rotated, revoked, and proven removed?

Knowledge check

Summary

A production variable model begins with classification and least privilege, not with a UI field. Inputs are contracts, variables are runtime data, protected/environment scopes are separate filters, group inheritance expands trust, and OIDC-backed retrieval can replace long-lived stored secrets. The safest design is the one that sends the fewest sensitive values to the fewest jobs for the shortest time.

Official references

• GitLab Docs — CI/CD variables
• GitLab Docs — CI/CD inputs
• GitLab Docs — Pipeline security
• GitLab Docs — External secrets in CI/CD
• GitLab Docs — OIDC authentication using ID tokens
• GitLab Docs — Connect to cloud services with OIDC
• GitLab Docs — Project-level CI/CD Variables API
• GitLab Docs — Group-level Variables API
• GitLab Docs — Predefined CI/CD variables
• GitLab Docs — Where variables can be used
• GitLab Docs — CI/CD YAML syntax reference
• GitLab CLI — variable commands
• GitLab CLI — variable set
• GitLab CLI — variable delete
• GitLab 19.3 — latest monthly release
• GitLab Docs — GitLab Secrets Manager (Self-Managed)