Secrets
reading time 3 mins
Secrets in Doppler work very similarly to how they would on any other platform, with a few exceptions. Our secrets engine has a couple of built-in perks!
Secret Names
Secret names must adhere to a specific format:
- Secret names may only contain uppercase letters, numbers, and underscores
- Secret names may not start with a number
For example, DATABASE_URL
is a valid secret name while 1secret_name
is not.
This strict format ensures that your secrets will work as expected when injected into an environment (regardless of the shell).
Doppler CLI
See our dedicated Doppler CLI User Guide to learn how to get started managing secrets from the command line.
Visibility
You can control the interaction with secrets in the dashboard and CLI by setting their visibility. See our dedicated page on Secret Visibility to learn more about how these work and how to use them!
Secret Notes
Now Doppler can centralize your documentation for app secrets and config by providing a notes field for every secret, scoped at the project level.
Multi-line Secrets
Doppler supports multi-line secrets such as PEM and SSH keys. These can be copy and pasted directly into the Doppler dashboard, or you can add them via the CLI:
cat ./id_rsa | doppler secrets set SSH_KEY
You can then supply multi-line secrets to your application as environment variables by using doppler run
or saving the secret to a file:
doppler secrets get SSH_KEY --plain > ./id_rsa
You can also use the Doppler CLI to create a Kubernetes TLS secret without a manifest file and the secrets ever touching the file system:
kubectl create secret tls doppler-test \
--cert <(doppler secrets get CERT_PEM --plain) \
--key <(doppler secrets get KEY_PEM --plain)
Multi-line Environment Variables for Every Language
Using
doppler run
to supply multi-line environment variables works flawlessly in every language and is one of the major benefits customers enjoy compared with .env files where multi-line support is patchy and incomplete at best.
This is great for scenarios where your application only reads the secrets once at runtime. By specifying a max reads value of 1, that will ensure that the file doesn't exist in the event an unauthorized actor gains access to the environment.
Referencing Secrets

The Doppler engine supports referencing secrets with the straightforward pattern ${SECRET_NAME}
. Here is an example:
Name | Value |
---|---|
USER | brian |
PORT | 3030 |
WEBSITE | ${USER}.doppler.com:${PORT} |
Now, when we access the WEBSITE
secret, the USER
and PORT
secrets will be inserted.
$ doppler secrets --raw
βββββββββββ¬βββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ
β NAME β VALUE β RAW β
βββββββββββΌβββββββββββββββββββββββββΌββββββββββββββββββββββββββββββ€
β PORT β 3030 β 3030 β
β USER β brian β brian β
β WEBSITE β brian.doppler.com:3030 β ${USER}.doppler.com:${PORT} β
βββββββββββ΄βββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββ
Referencing Across Projects

For workplaces on paid plans you can reference secrets across configs and projects. Users can only reference secrets they have access to, however secrets already being referenced will remain.
Type | Notation |
---|---|
Same config | ${SECRET_NAME} |
Across configs | ${config.SECRET_NAME} |
Across projects | ${project.config.SECRET_NAME} |
Now lets see this in practice! Here is what it would look like to reference the STRIPE_API_KEY
secret in the billing
project in the prd
config.
Type | Notation |
---|---|
Same config | ${STRIPE_API_KEY} |
Across configs | ${prd.STRIPE_API_KEY} |
Across projects | ${billing.prd.STRIPE_API_KEY} |
Unresolved References
Secret references are resolved at read-time. If the underlying resource is no longer available (e.g. it's renamed or deleted), Doppler will leave the reference string as-is.
For example, if
SECRET1
held the value${config.SECRET2}
, and either that config or secret were deleted, the full string including the${}
would be the computed value forSECRET1
.As soon as the target path (
config.SECRET2
) becomes resolvable, the value ofSECRET1
would immediately start injecting the reference. It is important to note that dangling references can pose a risk of unexpected values being injected at a later point in time.
Reserved Secrets
Doppler has a few special secrets you can use which makes it easier to track where you are in your CI/CD pipeline.
Name | Description | Example |
---|---|---|
DOPPLER_PROJECT | Identifier of current project | 58ded6ac873 |
DOPPLER_ENVIRONMENT | Identifier of the current environment | dev |
DOPPLER_CONFIG | Name of the current config | dev_stripe_billing |
Cascading Changes
Each property of a secret - its name, value, and visibility - can be changed independently. When choosing to apply changes to other environments in the save action, Doppler will only cascade properties that were changed to the other environments, similar to a PATCH update.
For example, if you update the visibility type of secret A in dev
and choose to apply changes to prd
, the value of secret A in prd
will be unchanged. If you update both the visibility type and value of secret A in dev
and choose to apply the changes to prd
, both of those properties will be updated in prd
.
Updated 13 days ago