GitLab CI/CD Variables and Secrets Explained

GitLab CI/CD variables provide configuration values to pipelines. Some values are ordinary settings; others are credentials. Security depends on where variables are defined, which pipelines can receive them, how job scripts use them, and whether untrusted code can print or transmit them.

Where variables can come from#

Masked, hidden, and protected behavior#

Masking reduces accidental display in job logs but is not a defense against malicious job code. Protected variables are limited to protected references under configured conditions. Hidden values reduce later UI exposure. Use these controls together with branch protection, runner isolation, and least privilege.

File-type variables#

File variables expose a temporary file path rather than placing the full value directly in a normal environment variable. They are useful for certificates or configuration documents, but job code can still read the file. Clean workspaces and restrict artifact collection.

Variable precedence#

The same key can be defined in multiple places. GitLab applies a documented precedence order, and higher-precedence values can replace lower-precedence ones. Review the resolved configuration and avoid reusing the same key for unrelated purposes.

Secure design practices#

• Prefer short-lived identity federation over long-lived cloud keys.
• Separate production secrets from general pipelines.
• Do not expose secrets to pipelines from untrusted forks.
• Use environment scope and protected references.
• Rotate credentials and record ownership and expiry.
• Prevent secret files and values from becoming artifacts or caches.
• Review third-party images and scripts before they receive credentials.

Incident response for a leaked secret#

1. Revoke or disable the credential immediately.
2. Identify pipelines, logs, artifacts, caches, and systems that received it.
3. Rotate dependent credentials and invalidate sessions.
4. Remove exposed data where possible without treating deletion as revocation.
5. Review how job code accessed the secret.
6. Add preventive controls and regression tests.

A variable feature is a delivery mechanism, not a complete secret-management system. High-value production credentials should be short-lived, narrowly scoped, auditable, and unavailable to untrusted code.

GitLab CI/CD variables documentation