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:
- Installing the Doppler CLI
- 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.
Updated 2 months ago