Secrets

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.

Finding Secrets

You can quickly find which projects and configs contain a particular secret by using the global search bar at the top of the dashboard. Type in the name of the secret and the projects that contain it will be listed. Click on the expansion arrow next to the project name to view which configs contain the secret.

Importing Secrets

Importing from Files

You can quickly import secrets in ENV, JSON, or YAML format by choosing the Import Secrets option from the dropdown next to the Add Secret button.

After choosing that option, you'll be presented with a form where you can paste what you want to import (you can also drag the file you want to import – assuming it's in a supported format – right into the field).

Once the import is complete, just save the config!

Importing from Another Config

You can import secrets from another Doppler config by choosing the Import from Other Config option.

This will pull in all the secrets form the Doppler config you select. After doing that, add, remove or modify any of the secrets it pulled in save the config!

Importing from the CLI

You can also import secrets via the Doppler CLI to accommodate more automated workflows. This command accepts ENV, JSON, or YAML formatted files.

doppler secret upload secrets.json

It's also possible to upload secrets from one config to another:

doppler secrets upload -p DESTINATION_PROJECT -c DESTINATION_CONFIG <(doppler secrets download -p SOURCE_PROJECT -c SOURCE_CONFIG --no-file --format json)

Valid Formats

ENV

AWS_ACCESS_KEY_ID="...."
AWS_SECRET_ACCESS_KEY="...."
DATABASE_URL="...."
STRIPE_API_KEY="...."

JSON

The expected JSON format for importing should look something like this:

{
  "AWS_ACCESS_KEY_ID": "....",
  "AWS_SECRET_ACCESS_KEY": "....",
  "DATABASE_URL": "....",
  "STRIPE_API_KEY": "...."
}

YAML

---
AWS_ACCESS_KEY_ID: "...."
AWS_SECRET_ACCESS_KEY: "...."
DATABASE_URL: "...."
STRIPE_API_KEY: "...."

Updating Across Environments

When adding or updating a secret, you're able to mirror the change to any of the other environments inside the project you're working in. This allows you to quickly modify any secrets that are the same across multiple configs all at once.

📘

Using secret references may work better in some scenarios where you would otherwise need to do this, so be sure to consider using those instead where it makes sense!

Missing Secret Detection

You'll be warned with a red box indicating how many secrets are missing whenever a secret is set in one environment but not another.

When you view one of those environments, you'll see an Action Required section indicating which secrets are missing. You'll have the opportunity to dismiss them if this is expected (which removes the red warning indicator).

If a missing secret accidentally gets dismissed, you can restore the warning as well by choosing Manage Dismissed Secrets from the project options menu.

You'll then have the option to choose which secrets you want to restore the warning for.

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!

Value Type

You can set a value type on a secret to have Doppler enforce that the provided value matches the given type. For example, if the value type is JSON, the value must be parseable as JSON. The default value type (string) will accept any value. Available value types to choose from include:

foo: bar
stuff:
  foo: bar
  bar: foo

Invisible Character Warning

You'll be warned whenever a secret contains an invisible or unusual character in it (e.g., trailing whitespace, invisible unicode characters, etc.). These can be introduced when copy and pasting secrets into Doppler and can be hard to track down after-the-fact. Each warning includes a button you can push to easily remove the characters in question!

Something similar also happens for non-ASCII characters like en dashes. For example, if a UUID contains en dashes rather than a standard ASCII dash, the recommended solution will convert all the en dashes to ASCII dashes.

Secret Reminders

You can setup a recurring reminder for any secret you create that will email the workplace's owners and admins when it triggers. This can be really useful when a particular credential needs to be rotated every so often or if you have a TLS certificate that needs to be renewed.

To set one up, click the clock icon on the right side of the secret value form field (it shows up when you hover over the form field).

You can then enter a message that's included in the reminder along with configuring when it should trigger.

Once the reminder is created, a clock icon will display in a yellow color indicating one is set. Clicking on the clock icon again will let you edit or delete the reminder.

Secret Generation

You can generate custom secrets right inside the Doppler dashboard by choosing the Generate option when hovering over a secret's value field. See our dedicated page on Secret Generation to learn how about how this works!

Version History

You can view past versions of a secret by clicking the ... icon in the secret row and choosing the Secret History option.

When that's selected, the access log pane will slide out. Click on the Version History tab to display past versions.

Redaction

When necessary, you can make a historical secret value entirely inaccessible. This process is known as redaction and applies to both the secret's version history and the config log.

To redact a secret, open the secret's version history. From there, you have a number of options. If you'd like all previous versions of the secret value to be redacted, click Redact All Historical Values. A modal dialog will appear asking you to confirm the redaction

If you'd like to redact a single historical value, click the yellow redact button next to the entry.

Note that it's not possible to redact the current version of a secret. To make the current secret value inaccessible, switch the secret's visibility to Restricted.

🚧

Redacting historical secret values is permanent! Once you redact a value, it will no longer be available in the Activity Logs or secret version history. This action cannot be reverted!

Notes

Doppler centralizes your documentation by providing a notes field for each secret. Notes are 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:

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} │
└─────────┴────────────────────────┴─────────────────────────────┘

📘

Disabling Secret Referencing

You can disable secret referencing at three different levels if you need to. In the workplace Settings page, you can disable it globally across all projects and configs in the workplace. It's also possible to disable this at the project level for all configs inside the project via the Secret Referencing option in the three-dot menu on the top right of the project config list view page. Finally, you can disable this at the individual config level by viewing the config and scrolling down to the External References section. You'll find a Settings button to the right of that section that will let you control this option.

📘

Trigger Behavior

When a secret that's being referenced is modified, all of the associated actions are triggered on the secret being referenced and the secrets doing the referencing. So, if the value of project1.dev.TESTis set to ${project2.dev.TEST} and project2.dev.TEST is updated, then any actions (e.g., webhooks, integration syncs, kubernetes deployment restarts, etc.) defined on both project1.dev and project2.dev will trigger. Also note that these actions occur as separate background jobs and as such are not performed atomically across all projects.

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.

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.

🚧

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 for SECRET1.

As soon as the target path (config.SECRET2) becomes resolvable, the value of SECRET1 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. You should track and update references that were moved and delete no longer useful references to prevent accidental filling in of that reference 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.

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.