In GitLab CI, what does the secrets: keyword do, and why might your application receive a file path instead of the secret value?

## The shape of the keyword ```yaml deploy: id_tokens: VAULT_ID_TOKEN: aud: https://vault.example.com secrets: DATABASE_PASSWORD: vault: production/db/password@ops token: $VAULT_ID_TOKEN file: false script: - ./deploy.sh ``` Three things are happening. `DATABASE_PASSWORD` is the variable the job will see. `vault:` names the path within the secret store, in GitLab's shorthand where the part after `@` is the mount. `token:` names the ID token the runner should present to authenticate. Alongside `vault:`, GitLab supports entries for Azure Key Vault, Google Secret Manager and AWS Secrets Manager, each with their own key and their own set of connection variables. Connection details for Vault come from variables the runner reads: the server URL, and optionally the auth path and role. Those are configuration, not secrets — which is the point, because there is no static credential anywhere in this pipeline. ## Who does the fetching, and when The **runner** resolves `secrets:` entries, not the GitLab server, and it does so before the job's script begins. The value is present in the environment from the first line. That ordering matters when you are debugging: a failure to resolve a secret fails the job before any of your commands run, so the error comes from the runner rather than from your script. ## The file-by-default trap This is the part that produces the support ticket. `secrets:` entries are delivered as **file**-type variables unless you say otherwise. So `$DATABASE_PASSWORD` holds a path, and code that treats it as a password sends the path as the password. The symptom is an authentication failure with a nonsense credential, and the log — if anything is printed at all — shows a plausible-looking temporary path rather than an obviously wrong value. The two correct responses: - Add `file: false` when the tool wants the value inline as an environment variable. - Keep the default and have the job use the file, which is what you want for a kubeconfig, a certificate, a service-account JSON or anything multi-line. Read it with `cat "$VAR"` or point the tool at the path; do not `echo` the variable expecting content. The default is not arbitrary: writing a secret to a file avoids it appearing in the process environment, which is visible to anything running in the container and often ends up in crash dumps and diagnostic output. ## Why use it rather than a project variable A project CI/CD variable is a copy. Once the value is pasted into GitLab, it lives in two systems, rotates on two schedules, and is readable by everyone with access to a job on a qualifying ref, forever. With `secrets:`, the value stays in one authoritative store, rotation happens in one place, the fetch is authenticated per job by a token that expires with the job, and the store's own audit log records which pipeline read which secret and when. The costs are real too: the runner needs network reachability to the manager, an outage there fails every deploy, the trust policy on the manager side has to be written and reviewed, and the feature is available on paid GitLab tiers. For a small project with two credentials, protected and masked project variables remain a defensible choice. ## Interaction with masking A value fetched at job time is not automatically covered by masking rules configured in project settings, and a file-delivered secret is not a candidate for masking anyway. The usual disciplines still apply: never echo it, keep it out of artifacts and reports, and prefer the file form so it is not sitting in the environment of every child process.