Item Value Functions

You may set config items values using functions rather than simple static values. Functions can be composed together to create complex value resolution logic.

ITEM=fn(arg1, arg2)
COMPOSITION=fn1(fn1Arg1, fn2(fn2Arg1, fn2Arg2))

Note that many built-in utility functions have expansion equivalents and often it will be more clear to use them that way. For example:

EXPANSION_EQUIVALENT="pre-${OTHER}-post"
USING_FN_CALLS=concat("pre-", ref(OTHER), "-post")

# mixed example
CONFIG=exec(`aws ssm get-parameter --name "/config/${APP_ENV}" --with-decryption`)

Currently, there are built-in utility functions, and soon there will be functions to handle values encrypted using varlock provided tools.

In the future, plugins will be able to register additional functions that fetch values from external providers.

concat()

Concatenates multiple values into a single string.

Expansion uses concat() to combine multiple parts of strings when they include multiple parts.

PATH=concat("base/", ref("APP_ENV"), "/config.json")
PATH2=`base/${APP_ENV}/config.json` # equivalent using expansion

exec()

Executes a CLI command and uses its output as the value. This is particularly useful for integrating with external tools and services.

NOTE - many CLI tools output an additional newline. exec() will trim this automatically.

Expansion equivalent: exec(command) === $(command)

# Using 1Password CLI
API_KEY=exec(`op read "op://dev test/service x/api key"`)
# Using AWS CLI
AWS_CREDENTIALS=exec(`aws sts get-session-token --profile prod`)

ref()

References another environment variable - which is very useful when composing multiple functions together.

Expansion equivalent: ref(OTHER_VARL) === ${OTHER_VAR} (and $OTHER_VAR)

API_URL=https://api.example.com
USERS_API_URL=concat(ref("API_URL"), "/users")

fallback()

Returns the first non-empty value in a list of possible values.

POSSIBLY_EMPTY=
ANOTHER=
EXAMPLE=fallback(ref(POSSIBLY_EMPTY), ref(ANOTHER), "default-val")

remap()

Maps a value to a new value based on a set of remapping rules. This is useful for translating one value, often provided by an external platform, into another.

• The first argument is the value to remap (often a ref() to another variable).
• All following arguments are key=value pairs, where the key is the new value and the value is what to match against, which can be a string, undefined, or a regex() call.
• If no match is found, the original value is returned.

# env var that is set by CI/platform
CI_BRANCH=

# @type=enum(development, preview, production)
APP_ENV=remap($CI_BRANCH, production="main", preview=regex(.*), development=undefined)

regex()

Creates a regular expression for use in other functions, such as remap().

• Takes a single string argument, which is the regex pattern (using JavaScript regex syntax)
• This cannot be used as a standalone value. It must be used only as a function argument.

# Example usage within remap
ENV_TYPE=remap($APP_ENV, dev=regex("^dev.*"), prod="production")