YAML !ENV Tag

A custom YAML tag for referring environment variables in YAML files. No need to use ERB in YAML just to set some keys from environment variables.

Sample YAML file using !ENV tag

oauth:
  base_uri: !ENV API_BASE_URI
  client_id: !ENV [API_CLIENT_ID, "demo"]
  client_secret: !ENV [API_CLIENT_SECRET, API_CLIENT_KEY, ~]

Usage

Just require yaml-env-tag and load YAML as you’re used to:

require 'yaml-env-tag'

yaml = YAML.safe_load('secret: !ENV API_CLIENT_SECRET', permitted_classes: [YamlEnvTag::EnvVariable])
yaml['secret']  # => "top-secret"

Note: Since Ruby 3.1, YAML.load is an alias for YAML.safe_load, which means you have to explicitly whitelist the YamlEnvTag::EnvVariable class (see keyword argument permitted_classes). Analogously, YAML.load_file became an alias for YAML.safe_load_file. Also keep in mind that the safe variant disables aliases (anchors); you can enable them by setting the aliases parameter to true (e.g. YAML.safe_load(…, aliases: true)). For compatibility with older Ruby versions, it’s better to always use YAML.safe_load and YAML.safe_load_file.

Single Required Variable

Specify one environment variable as a !ENV tagged scalar. If it does not exist (is not set), YAML.load (and other load methods) will raise YamlEnvTag::MissingEnvVariableError.

!ENV SOME_VARIABLE

This can be also written as a tagged sequence !ENV [SOME_VARIABLE] or !ENV [SOME_VARIABLE, ~], all three variants are equivalent.

Default Value

You can define a default value that is used when the specified environment variable does not exist. This makes the variable optional. Default value is the last element of a !ENV tagged sequence (array) with more than one element.

!ENV [SOME_VARIABLE, "default value"]

Multiple Variables (Fallbacks)

You may also specify more environment variables in a !ENV tagged sequence (array) – the first one that does exist is used. Keep in mind that the last element of a multi-element sequence is always interpreted as a default value, not a name of environment variable!

!ENV [SOME_VARIABLE, LEGACY_VARIABLE, "default value"]

If you want to raise an exception when none of the specified environment variables exist, use ~ (nil) as the last element:

!ENV [SOME_VARIABLE, LEGACY_VARIABLE, ~]

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.