CI/CD Variables, Predefined Variables, File Variables, Masking, Protection, Expansion, and Precedence: Concepts, Architecture, and Mental Model

1. The problem: identical names can represent different state

A pipeline can contain DEPLOY_TARGET in four or more places and still produce one effective value in a job. The repository may define a default, a job may override it, the project settings may define the same key, and a manually started pipeline may pass another value. If you inspect only .gitlab-ci.yml, you can be looking at a lower-precedence value that never reaches the job.

Variables also exist at different times. Some predefined values exist before pipeline creation, some while GitLab constructs the pipeline, and some only after a runner starts the job. A value that exists only in the job environment cannot retroactively influence include:rules or decide whether that job was added to the graph.

2. Mental model: variable provenance becomes an effective value

            flowchart TD
              A[Definition sources] --> B[Scope + type + protection]
              B --> C[Availability phase]
              C --> D[Precedence resolution]
              D --> E[Compiled pipeline / job environment]
              E --> F[GitLab or Runner expansion]
              F --> G[Shell expansion / tool consumption]
              G --> H[Logs, files, reports, external side effects]
              H --> I[Exposure and audit evidence]
          

The diagram is causal. Definition source and access controls determine whether a value is eligible. Availability timing determines whether GitLab can use it during compilation. Precedence chooses among eligible values with the same key. Expansion can then happen in GitLab, in Runner, or in the execution shell. Finally, job code can consume, transform, log, upload, or accidentally exfiltrate the result.

3. Every variable has multiple dimensions

4. Predefined variables have availability phases

GitLab documents three availability phases. Pre-pipeline values exist before the pipeline is created and are the only predefined variables available to include:rules. Pipeline values exist while GitLab constructs the pipeline and can participate in job rules. Job-only values arrive only when a runner executes a job.

5. Current precedence is a ladder, not “nearest YAML wins”

GitLab resolves duplicate keys by source precedence. The current documentation places policy variables at the top for the jobs those policies add, then manual-job variables, then pipeline variables, project variables, group variables, instance variables, dotenv variables, YAML variables, deployment variables, and most predefined variables. Within YAML, rules:variables outranks job variables, which outrank workflow:rules:variables, which outrank top-level default variables.

6. Ordinary and file type variables solve different interface problems

An ordinary variable arrives as an environment key/value pair. A file type project/group/instance variable stores the configured value in a temporary file and exposes the file path through the environment variable. This is useful when a tool expects --config FILE, a certificate path, or another file-oriented interface.

Predefined variables and variables defined directly in .gitlab-ci.yml are ordinary variable type. You cannot mark a YAML variable as file type; if a YAML value must become a file, your job writes it to a controlled file explicitly.

inspect_file_variable:
  script:
    - test -n "${LAB_CONFIG_FILE:-}"
    - test -f "$LAB_CONFIG_FILE"
    - printf 'file_path=%s\n' "$LAB_CONFIG_FILE"
    - printf 'bytes=%s\n' "$(wc -c < "$LAB_CONFIG_FILE")"
    - sha256sum "$LAB_CONFIG_FILE" | sed 's/  .*/  <temporary-file>/' 

7. Masking, hiding, and protection are different controls

GitLab explicitly warns that masking is not a guaranteed defense against malicious scripts. Review CI configuration before running it with valuable variables, especially for fork/merge-request scenarios. A transformed value may no longer match the masker’s exact pattern.

8. Expansion happens in more than one place

“The variable expands” is incomplete. GitLab can expand some values before handing a job to Runner; Runner performs expansion for supported fields; and then the shell expands environment references while executing the script. These layers use different syntax and timing.

variables:
  BASE_FRAGMENT: "blue"
  EXPANDED_FRAGMENT: "$BASE_FRAGMENT-canary"
  LITERAL_FRAGMENT:
    value: "$BASE_FRAGMENT-canary"
    expand: false

show_expansion:
  script:
    - printf 'expanded=%s\n' "$EXPANDED_FRAGMENT"
    - printf 'literal=%s\n' "$LITERAL_FRAGMENT"

For UI-defined variables, current GitLab documentation says variable-reference expansion is disabled by default. Masked/hidden values should not be combined with expansion. Treat expansion as a configuration feature for non-secret composition, not as a secret templating system.

9. Variables are data channels; repository code is the consumer

A variable can be encrypted at rest, masked in normal logs, hidden in settings, and protected to a ref—yet still be exfiltrated by malicious commands that legitimately receive it. The primary control is therefore which code is allowed to execute with which variable, on which ref, runner, and identity boundary.

• Do not use env, printenv, shell tracing, or full context dumps in variable troubleshooting.
• Print an allowlist of non-sensitive identifiers such as pipeline source, SHA, job ID, and a synthetic demo value.
• Do not transform or encode a real secret to “test masking.” If teaching the limitation, use a fake synthetic string only.
• Do not put secrets in artifacts, caches, dotenv reports, or debug bundles merely because the source variable was masked.

10. Read-only inspection: prove context before changing values

printf 'pipeline_source=%s\n' "$CI_PIPELINE_SOURCE"
printf 'pipeline_id=%s\n' "$CI_PIPELINE_ID"
printf 'job_id=%s\n' "$CI_JOB_ID"
printf 'ref=%s\n' "$CI_COMMIT_REF_NAME"
printf 'sha=%s\n' "$CI_COMMIT_SHA"
printf 'runner_id=%s\n' "${CI_RUNNER_ID:-unknown}"
printf 'runner_desc=%s\n' "${CI_RUNNER_DESCRIPTION:-unknown}"

These values identify the execution context without enumerating arbitrary variables. Pair them with the project Settings → CI/CD → Variables metadata for the specific synthetic lab keys you are studying. Do not screenshot or export secret values.

11. Foundation mistakes to eliminate early

• “Job YAML wins because it is closer to the script.” Project/group/pipeline sources can outrank YAML entirely.
• “Masked means secret code cannot read it.” Masking is primarily a log-redaction mechanism.
• “File variable means the value is not in the job.” The job receives a path to a temporary file containing the value and can read it.
• “Protected variable exists in every pipeline.” Availability depends on protected-ref context and current MR behavior.
• “All predefined variables exist during rules evaluation.” Job-only variables do not.
• “Expansion is just shell expansion.” GitLab and Runner also perform keyword-specific expansion before the shell runs.

Knowledge check

Official references and version notes

• GitLab CI/CD variables — project/group/instance variables, visibility, masking, hiding, protection, file variables, expansion, precedence, pipeline-variable restrictions, and security guidance.
• Predefined CI/CD variables reference — current pre-pipeline, pipeline, and job-only availability phases and variable definitions.
• Where variables can be used — GitLab, GitLab Runner, and execution-shell expansion mechanisms and keyword-specific behavior.
• CI/CD YAML syntax reference — variables, job variables, variables:expand, rules:variables, workflow:rules:variables, and inheritance semantics.
• CI/CD inputs — typed/configuration inputs, interpolation, and the current recommendation to prefer inputs over ad-hoc pipeline variables for newer parameterized pipelines where applicable.
• Protected branches — current protected-ref behavior that underpins protected-variable availability.