Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Security and Compliance

CI Variables and Secrets Security

Handle secrets safely in GitLab CI/CD: masked, protected and hidden variables, file variables, variable precedence, job tokens, OIDC ID tokens and external secret stores.

Pipelines need secrets: deployment keys, registry passwords, API tokens. Every secret is also a risk. If it leaks into a job log, a public repository or a merge request from an untrusted fork, someone else can act as you. GitLab gives you several layers of protection, and this lesson shows how to use each one and how they fit together.

The rule behind all of them is simple: never store a secret in the repository, give each job only the secrets it needs, and prefer short-lived credentials over long-lived ones. GitLab itself cannot run on this site, so the YAML and menu paths are descriptive; the examples are JavaScript models of the rules.

Where variables come from

Variables can be defined in several places:

  • variables: in .gitlab-ci.yml: visible to everyone who can read the repository. Use only for non-secret settings.
  • Project settings > CI/CD > Variables: stored outside the repository.
  • Group and instance variables: shared by many projects.
  • Predefined variables such as CI_COMMIT_SHA, CI_JOB_TOKEN, CI_REGISTRY_USER.
  • Variables passed when you run a pipeline by hand, or by a trigger or schedule.

When the same name exists in several places, the more specific one wins. In rough order, from strongest to weakest: pipeline-level and manual values, project variables, group variables, instance variables, then variables in the YAML file and predefined defaults. The documentation has the exact table; the practical lesson is that a project variable overrides a group variable of the same name.

Variable options that matter for security

When you add a variable in the settings you get several switches:

Option Effect
Protected Only pipelines on protected branches or protected tags receive it
Masked The value is replaced by [MASKED] in job logs
Masked and hidden Masked, and the value can never be shown again in the settings after saving
Environment scope Only jobs of matching environments (production, review/*) receive it
Type: File The value is written to a temporary file, and the variable holds its path
Expand variable reference Whether $OTHER inside the value is expanded

Masking has limits. The value must be at least 8 characters and use only characters from a restricted set (letters, digits and a few symbols, without spaces), so some passwords cannot be masked. Masking only matches the exact text: if your script prints the value in a different form (Base64-encoded, reversed, split by echo), the log shows the secret. Masking is a safety net for accidents, not a way to make echo $SECRET safe.

Protected plus scoped is the strongest everyday combination. A production deploy key marked Protected, scoped to production, is received only by jobs that run on main (a protected branch) and deploy to the production environment. A developer's experimental branch never receives it (see Roles, Permissions and Protected Branches).

File variables

Some tools want a file, not a string: a kubeconfig, a service account JSON, an SSH key. Create the variable with type File. GitLab writes the content to a temporary file in the job and puts the file path into the variable:

YAML
deploy:
  script:
    - kubectl --kubeconfig "$KUBECONFIG" get pods

$KUBECONFIG is a path such as /builds/group/project.tmp/KUBECONFIG. Do not cat it, and keep in mind that the file exists for the job only.

Keeping secrets out of logs and artifacts

Habits that prevent leaks:

  1. Never echo a secret and avoid set -x in scripts that use secrets, because shell tracing prints expanded values.
  2. Do not run env or printenv in jobs; they print every variable, including secrets that masking does not recognize.
  3. Do not put secrets into artifacts, caches or built images. Anything inside an image layer can be extracted, even if a later RUN rm deleted the file.
  4. Be careful with merge requests from forks: untrusted code could print secrets. Protected variables are not sent to such pipelines, and you should keep "Run pipelines for forks" settings tight.

Job tokens and deploy tokens

A job can talk back to GitLab with CI_JOB_TOKEN, a short-lived token that exists only while the job runs. It pulls images and packages and triggers downstream pipelines. Since newer versions you can restrict which projects may be accessed with a project's job token: the job token allowlist in the project's CI/CD settings names the projects permitted to use the token for access. Keep it as small as you can.

For access from outside a pipeline there are deploy tokens (read-only access to the repository, registry or package registry for a server or customer) and project access tokens (a bot user with a role and an expiry date). Give both a short expiry and the minimum scopes.

Short-lived credentials: ID tokens and OIDC

The best secret is the one you never store. With the id_tokens keyword a job asks GitLab for a signed JSON Web Token that proves "this job, from this project, branch and environment". A cloud provider can be set up to trust GitLab as an identity provider and exchange the token for temporary credentials:

YAML
deploy:
  id_tokens:
    CLOUD_ID_TOKEN:
      aud: https://cloud.example.com
  script:
    - ./exchange-token-for-credentials.sh "$CLOUD_ID_TOKEN"
    - ./deploy.sh

The aud (audience) must match what the provider expects. The cloud side checks claims such as the project path and the ref_protected flag, so only protected branches get the deploy role. Credentials expire within minutes, which removes the long-lived key that could leak.

External secret managers

Large organizations keep secrets in a dedicated system such as HashiCorp Vault, AWS Secrets Manager, Google Secret Manager or Azure Key Vault. GitLab's secrets: keyword reads values from supported providers using an ID token for authentication, and puts them in the job (as a file by default). The secret then never lives in GitLab's settings at all.

Stand-in: masking rules and variable resolution

The first example checks whether a value can be masked, using the rules above (length of at least 8, restricted characters), and shows what a log line looks like. The character set here is a simplified model of the real rule.

JS Can this value be masked?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example resolves which variables a job receives. It combines precedence, the protected flag and the environment scope.

JS Which variables reach this job?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice the last line: a job on an unprotected branch that claims the production environment still does not get DEPLOY_KEY, because protection filters first.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which variable setting keeps a production key away from jobs on feature branches?

    Protected variables are passed only to pipelines on protected branches and tags. Masking only hides values in logs.
  2. 2. Why is masking not a complete defense?

    The log filter replaces the literal value. Base64, reversed or split output does not match and passes through.
  3. 3. What is an advantage of ID tokens with OIDC over a stored cloud key?

    The cloud provider exchanges the signed token for temporary credentials, so there is no long-lived key to steal.
  4. 4. Why should you avoid running env or set -x in jobs that use secrets?

    env prints every variable and set -x prints expanded commands, both writing secrets into the log.
  5. 5. What does a File-type variable contain inside the job?

    Tools such as kubectl take a file path, so GitLab writes the content to a file and gives you its location.

Summary

  • Keep secrets out of the repository; store them in project, group or instance variables, or fetch them from a secret manager.
  • Combine Protected, Masked (or hidden) and environment scope; masking only helps against accidental printing.
  • Use File variables for tools that need a file, and never print or cache secrets.
  • Prefer short-lived credentials: CI_JOB_TOKEN, token allowlists and OIDC through id_tokens.

Next: Security Scanning: SAST, Secrets and Dependencies