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

Prerequisites

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

CircleCI Environment

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

Now we can bring your existing CircleCI environment variables to your Doppler CircleCI config. Once all variables have been entered, click Save.

Service Tokens

Create a Doppler Service Token that the Doppler CLI will use to access your secrets by selecting the Access tab, then click the Generate button.

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 DOPPLER_TOKEN using the token content copied to the clipboard.

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'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.

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

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 -- printenv | grep DOPPLER # Testing purposes only

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

📘

Embed the Doppler CLI in a CircleCI specific Docker image

A common pattern we see is using a custom-built Docker image for CI jobs and we recommend pre-installing the Doppler CLI in that image to remove the install step from your jobs.

Multiple Environments

If your jobs require specific variables for different environments, e.g. preview vs. production builds, then you'll need a different approach than using a single DOPPLER_TOKEN environment variable.

The solution is to use Doppler branch configs to create environment-specific configs.

Then create a Doppler Service Token and CircleCI environment variable for each config.

Then the doppler run command will need to use the --token flag as the DOPPLER_TOKEN environment variable does not now exist. An example of a job that only builds on the master branch that uses a production service token could look like the following.

version: 2.1

jobs:
  build:
    docker:
      - 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: Production build secrets access
          command: doppler run --token $DOPPLER_TOKEN_PRODUCTION -- printenv | grep DOPPLER # Testing purposes only
    filters:
      branches:
        only:
          - master

👍

Amazing Work!

Now you are all set up using the Doppler CLI to provide secrets to your CircleCI jobs in both single, and multi-environment workflows.