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:

• CircleCI Doppler Integration Sync
  • Automatically syncs secrets from Doppler to CircleCI's Project Environment Variables whenever they are updated
  • Can only be used with a single environment
  • Recommended unless your builds require secrets across multiple environments
• Doppler Service Tokens
  • Grant CircleCI access to fetch secrets from Doppler and use the Doppler CLI in your builds to access your secrets
  • Can be used with multiple environments

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

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.

Option 1: CircleCI Integration Sync

🚧

Single Environment Only

This option only works for single environment builds. If you need to support multiple environments in CircleCI, skip to Option 2: Service Tokens.

Import Variables

Let's start by bring over your existing CircleCI environment variables to your Doppler CircleCI config. Once all variables have been entered, click Save.

In your project, navigate to Integrations and select CircleCI:

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 specific variables for different environments, e.g. preview vs. production builds, then you'll need a different approach.

The solution is to use Doppler branch configs to create environment-specific configs. Then we'll generate several Doppler Service Tokens which allow CircleCI to fetch secrets from Doppler when you build runs.

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.

📘

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.

👍

Amazing Work!

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