Variables

Configuration values can refer to variables with $NAME or ${NAME}.

Where values come from

A reference is resolved from these places, highest precedence first:

1. The variables: block in the config.
2. The predefined variables below.
3. Your process environment.

The environment fallback is broad. Any variable your shell exports can be read by a config, including a remote fragment you extend. See Security.

Defining variables

Defaults and required checks belong in the variables: block:

variables:
  DOMAIN: ${DOMAIN:-example.test}   # the environment's DOMAIN, or example.test
  SHELL_VERSION:
    type: file                      # read the value from a file
    path: ./config/GITLAB_SHELL_VERSION

cluster:
  network:
    hostname: gitlab.${DOMAIN}

With DOMAIN unset, xianyun config print shows gitlab.example.test. With DOMAIN=lab.test exported, it shows gitlab.lab.test. A file-typed variable reads its value from the named path, relative to the config file or absolute.

Inside a variables: definition you can use ${NAME:-default}, ${NAME:?message}, and ${NAME:+alternate}. Anywhere else those forms are rejected as unsupported expansions. Plain references also support length (${#NAME}), indirection (${!NAME}), slices, replacement, and prefix and suffix removal.

Predefined variables

CAPRONI_CLUSTER_NAME, CAPRONI_PRIMARY_HOSTNAME, and CAPRONI_CLUSTER_DOMAIN still work and mean the same thing.

What never runs

$(command), backticks, and $((arithmetic)) are left exactly as written. Xianyun doesn’t run a command from configuration or compute one. That’s deliberate, and it matters in fields like script where those constructs belong to the shell that eventually runs the value.

Escape a dollar sign with a backslash to keep it from being treated as a reference: \$HOME stays the text $HOME.

Fields that must be literal

cluster.driver and k3s.disable can’t contain $. A repository ref can’t contain an unresolved variable. Xianyun rejects the config rather than guess.