New CLI Command: `circleci env subst`

Announcements
1

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
2 Likes