CircleCI’s CLI now includes an env subst
command, both in the local CLI and running inside all CircleCI jobs (coming to CircleCI server v4.2+).
If you currently have the CircleCI CLI installed, run the circleci update
command.
Release: v0.1.25848
Changelog: https://circleci.com/changelog/#new-cli-command-env-subst
Docs: Introduction to environment variables - CircleCI
The new circleci env subst
command is a wrapper around the popular envsubst
CLI tool, used to substitute environment variables in a text string or file.
Usage:
circleci env [command]
Available Commands:
subst Substitute environment variables in a string
Global Flags:
--verbose enable verbose logging output
Use "circleci env [command] --help" for more information about a command.
Example Usage
Assuming you have a file named template.json
:
{
"key": "$value"
}
With the $value
environment variable set, the template can be processed like so:
jobs:
env-subst-example:
docker:
- image: cimg/base:current
environment:
value: example
steps:
- checkout
- run:
command: circleci env subst < template.json > output.json
The expected contents of output.json
will be:
{
"key": "example"
}
Usage In Orbs
Envsubst is an especially helpful utility when developing orbs. It is common when creating orb commands to set environment variables to the values of CircleCI Config Parameters so that they may be used within a native bash script. This can, however, be difficult to deal with when the parameter values are expected to support string values or environment variable strings; such as $REGION
or US_EAST
.
Example Orb Command:
description: >
An orb command
parameters:
param:
default: '$REGION'
steps:
- run:
name: command script
environment:
PARAM: <<parameters.param>>
command: <<include(scripts/my-script.sh)>>
In this example, the PARAM
environment variable value in my-script.sh
will be the literal string $REGION
. While we could eval
the variable, this can have unintended consequences if the value contains certain symbols such as =
.
Inside the my-script.sh
file, if we want to safely evaluate a string parameter that may contain an environment variable, we can process it with env subst
at the beginning of our script.
PARAM=$(circleci env subst "$PARAM")
This will replace the environment variables within the parameter string if any exist.
If PARAM
was equal to $REGION
, it would now be US_EAST
If PARAM
was equal to US_EAST
, it would now be US_EAST
Kubernetes Example
A common use for the envsubst utility is for processing development config templates, such as Kubernetes values.yaml
files.
Example values.yaml
:
# Database settings
database:
type: postgres
host: localhost
port: 5432
user: ${MY_USER}
password: ${MY_PASSWORD}
name: mydb
Load secrets injected into the CircleCI environment (example: contexts)
circleci env subst < values.yaml > config.yaml