This guide will show you how to use Doppler to provide secrets to CircleCI jobs for both single, and multi-environment build or deployments.

There are two main ways to use CircleCI with Doppler:

Option 1: Sync Individual Secrets
Syncs individual secrets and recommended if jobs require secrets from a single Doppler config.

Option 2: Service Tokens
Provide secrets from multiple Doppler configs by using Service Tokens and installing the Doppler CLI in your chosen executors.

Prerequisites

• You have created a project in Doppler
• You have an existing CircleCI project and have access to set environment variables for that project

🚧

Empty Secret Values

CircleCI currently doesn't accept secrets with empty secret values. If you save a secret in Doppler without a value, it won't be synced properly to CircleCI and that secret will retain the last value it had before it was cleared in Doppler. Furthermore, secrets initially created with empty values in Doppler will not be synced at all and won't show up in CircleCI. As such, it's recommended that for now you simply remove any secrets with no value set in Doppler to avoid confusion.

CircleCI Environment

Whether you're using the integration sync or service token method, we'll need a config for CircleCI. As CircleCI doesn't exactly fit into Development, Staging, or Production, we'll create a custom environment. Head to the Project page, then click on Options.

Now click Create Environment.

Give the environment a name, e.g. CircleCI and a short name, then click Create New.

Next, you can drag-and-drop the CircleCI environment to alter its position, e.g. before Staging.

Import Variables

Before integrating Doppler with CircleCI, you'll need to perform the one-time manual task of importing your current environment variables into your Doppler CircleCI config. Once all variables have been entered, click Save.

Option 1: Sync Individual Secrets

Syncs individual secrets and recommended if jobs require secrets from a single Doppler config.

Follow the setup link to setup a new CircleCI Personal API Token. Give the token a name and copy the token value into Doppler and click Connect.

Select your CircleCI project and our newly-created ci environment:

Click "Setup Integration" and you're all set! The secrets from your selected config will be immediately and continuously synced to your CircleCI project's Environment Variables. These variables can be used directly in your CircleCI config.

If you'd like to learn about how to setup CircleCI with multiple environments, read on.

Option 2: Service Tokens

If your jobs require secrets from different environments (e.g. preview and production), we recommend the use of branch configs and service tokens Service Token.

A service token is then used by the Doppler CLI to inject secrets for a specific config inside the executor.

Let's create branches from ci for our preview and production environments:

For each branch, create a Doppler Service Token by selecting the Access tab, then click the Generate button.

Provide a name and then copy the Service Token value which we will then use to create a new CircleCI environment variable.

Now in CircleCI go to Project Settings > Environment Variables and add a new variable for your environment using the token content copied to the clipboard. Choose a name like "DOPPLER_TOKEN_PREVIEW", based on the name of your environment. We'll use this new variable in the next section.

Repeat this process for each environment.

Service Token Usage

There are only two steps required to modify your existing CircleCI config to use Doppler:

1. Installing the Doppler CLI
2. Using doppler run to supply secrets to your build steps.

We will choose which environment we want to use in the CircleCI config by using the --token CLI flag.

We'll now show you two different examples to cover the most common executors: a Linux machine and Docker executor.

📘

If using an executor not shown here, e.g. Windows, see our Installation guide to learn how to install the Doppler CLI for that environment.

Linux Executor

As the machine executor is likely to be heavily a restricted environment, preventing package installation and write access to directories such as /usr/local/bin, we will alter the standard Doppler CLI install command to download the binary to the current directory. This means accessing the binary will be done using ./doppler.

Here we're loading our "preview" environment with ./doppler run --token $DOPPLER_TOKEN_PREVIEW.

version: 2.1

jobs:
  build:
    machine:
      image: ubuntu-2004:202010-01
    steps:
      - checkout
      - run:
          name: Install Doppler CLI to current directory
          command: (curl -Ls https://cli.doppler.com/install.sh || wget -qO- https://cli.doppler.com/install.sh) | sh -s -- --no-install --no-package-manager
      - run:
          name: Test Doppler secrets access
          command: ./doppler run --token $DOPPLER_TOKEN_PREVIEW -- printenv | grep DOPPLER # Testing purposes only

A successful job run should produce output similar to the following:

Docker Executor

The standard command for installing the Doppler CLI should work when using the Docker executor unless the USER directive has been set to not be root.

Here again, we're loading our "preview" environment with doppler run --token $DOPPLER_TOKEN_PREVIEW.

version: 2.1

jobs:
  build:
    docker:
      # Best to create a build specific image with the Doppler CLI pre-installed
      - image: alpine
    steps:
      - checkout
      - run:
          name: Install Doppler CLI
          command: (curl -Ls https://cli.doppler.com/install.sh || wget -qO- https://cli.doppler.com/install.sh) | sh
      - run:
          name: Test Doppler secrets access
          command: doppler run --token $DOPPLER_TOKEN_PREVIEW -- printenv | grep DOPPLER # Testing purposes only

A successful job run should produce output similar to the following.

📘

Install the Doppler CLI in Docker Build Executor

We recommend pre-installing the Doppler CLI in your custom build image to remove the install step from your job and reduce build times.

👍

Amazing Work!

Now you know how to integrate Doppler with CircleCI to sync secrets individually, or using service tokens and the Doppler CLI to supply secrets for multiple environments.