Rule options

Every option a rule can have, and where it may be set. A rule is built from up to three files, each laid over the one before (how): config.cue, the tenant's bundle.json, and the pushed repository's vartrack.json; then config.cue's force block.

Column	Meaning
config.cue	The rule in the bundle every service reads. Every option can be set here.
bundle.json	The tenant's layer, in its schema repository. An option only config.cue sets is dropped from it with a warning.
vartrack.json	The repository's layer. Any other option there is ignored and logged.
Across layers	What happens when two layers set the option.

Option	Type	config.cue	bundle.json	vartrack.json	Across layers
platform	string	yes	names the rule	—	names the rule (with platform/datasource): not changed by a layer
datasource	string	yes	names the rule	—	names the rule (with platform/datasource): not changed by a layer
repositories	list	yes	—	—	only config.cue sets it
file_name	string	yes	yes	yes	the upper layer replaces it
file_path_map	object (string → string)	yes	yes	yes	merged key by key
branch	string	yes	yes	—	the upper layer replaces it
root_key	string	yes	yes	yes	the upper layer replaces it
branch_as_env	boolean	yes	yes	yes	the upper layer replaces it
pr_as_env	boolean	yes	yes	yes	the upper layer replaces it
tag_as_env	boolean	yes	yes	yes	the upper layer replaces it
branch_map	object (string → string)	yes	yes	yes	merged key by key
secret_manager	string	yes	—	—	only config.cue sets it
destination_template	string	yes	yes	—	the upper layer replaces it
variables_map	object (string → string)	yes	yes	yes	merged key by key
sync_mode	string: AUTO, GIT_UPSERT_ALL, GIT_SMART_REPAIR	yes	yes	yes	the upper layer replaces it
exclude_repositories	list	yes	—	—	only config.cue sets it
overrides	list	yes	—	—	only config.cue sets it
prune	boolean, or object (enabled, protection)	yes	yes	yes	merged key by key; protection patterns add up
self_heal	boolean	yes	—	—	only config.cue sets it
force	object	yes	—	—	only config.cue sets it
tenants	list	yes	—	—	only config.cue sets it
suspend	boolean	yes	yes	—	the upper layer replaces it
drift_ignore	list	yes	yes	—	the upper layer replaces it
strict_validation	boolean	yes	yes	yes	the upper layer replaces it
schema_map	list	yes	yes	—	the upper layer replaces it
schema_from_file	boolean	yes	yes	—	the upper layer replaces it
repo_url	string	yes	yes	—	the upper layer replaces it
key_format	string	yes	yes	—	the upper layer replaces it
file_format	string	yes	yes	—	the upper layer replaces it
env_as_filename	boolean	yes	yes	—	the upper layer replaces it
helm_values_mode	string	yes	yes	—	the upper layer replaces it
s3_object_tags	object (string → string)	yes	yes	—	the upper layer replaces it
s3_tag_keys	list	yes	yes	—	the upper layer replaces it

platform

The platform that sends this rule's pushes: a platforms entry's name, "github", "gitea", or "{type}-{tag}" for a tagged one. With datasource it names the rule: a bundle.json rule layers the config.cue rule with the same platform and datasource, and there is at most one of each pair.

Type	string
Set in	config.cue, bundle.json
Across layers	names the rule (with platform/datasource): not changed by a layer

datasource

Where the rule writes: a datasources entry's name, "mongo", "redis", or "{type}-{tag}" for a tagged one ("mongo-billing").

Type	string
Set in	config.cue, bundle.json
Across layers	names the rule (with platform/datasource): not changed by a layer

repositories

The repositories whose pushes this rule syncs, as "owner/name" glob patterns ("acme/", "acme/payments-"). The gateway routes a push by them.

Type	list
Set in	config.cue
Across layers	only config.cue sets it

file_name

Explicit single file to track in every repository. Mutually exclusive with file_path_map (validated below).

Type	string
Set in	config.cue, bundle.json, vartrack.json
Across layers	the upper layer replaces it

file_path_map

Maps environment label → file path for per-env config files.
e.g. { "production": "config/prod.json", "staging": "config/staging.json" }

Type	object (string → string)
Set in	config.cue, bundle.json, vartrack.json
Across layers	merged key by key

branch

The rule's own branch: it feeds the file_path_map environments, and it is the branch the periodic self-heal compares when the rule has no branch_map (with a branch_map, every branch in it is healed). "main" when unset.

Type	string
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

root_key

Top-level key to extract from the parsed file BEFORE flattening. Only that subtree is written to the sink.

Default behaviour (field absent or unset):
  → "vartrack" is used as the key.
  → If the file contains a "vartrack" key, only that section is synced.
  → If "vartrack" is absent, the WHOLE FILE is used (soft fallback).

Set to "" to always process the entire file regardless of its contents.

Examples:
  root_key: "properties"  → sync only the "properties" object
  root_key: "vartrack"    → (default) sync "vartrack" section or whole file
  root_key: ""            → always sync whole file

Works the same way for every supported format (JSON, YAML, TOML, XML, .env, .properties, HCL, INI, JS module): the key is looked up after the file is parsed.

Type	string
Set in	config.cue, bundle.json, vartrack.json
Across layers	the upper layer replaces it

branch_as_env

The branch name is the environment. Formerly env_as_branch.

Type	boolean
Set in	config.cue, bundle.json, vartrack.json
Across layers	the upper layer replaces it
Former names	env_as_branch — still read, with a warning

pr_as_env

"pr-{number}" is the environment. Formerly env_as_pr.

Type	boolean
Set in	config.cue, bundle.json, vartrack.json
Across layers	the upper layer replaces it
Former names	env_as_pr — still read, with a warning

tag_as_env

The tag name is the environment. Formerly env_as_tags. The former names are still read from bundles and vartrack.json.

Type	boolean
Set in	config.cue, bundle.json, vartrack.json
Across layers	the upper layer replaces it
Former names	env_as_tags — still read, with a warning

branch_map

Branch → environment, e.g. {main: "production", develop: "staging"}.
A push to a branch that is not listed, and that no file_path_map,
branch_as_env, pr_as_env or tag_as_env places, feeds no environment of
the rule: it is skipped, not written anywhere. There is no "default"
environment; a rule has to name where its environments come from (this,
file_path_map, branch_as_env, pr_as_env or tag_as_env) in config.cue or the
tenant's bundle.json, or it is refused when it is loaded. To keep writing
to an environment called default, map a branch to it: {main: "default"}.

Type	object (string → string)
Set in	config.cue, bundle.json, vartrack.json
Across layers	merged key by key

secret_manager

The secret manager (a secret_managers entry: "vault" or "vault-{tag}") that {ref: …} credentials of this rule's platform and datasource, and its @secret() fields, are read from. Unset: the entry tagged "default", else the bundle's only one.

Type	string
Set in	config.cue
Across layers	only config.cue sets it

destination_template

Universal storage path / key / name template for the sink. Supported placeholders: {tenant}, {env}

Sink        Interpretation               Example
zookeeper   znode root path              "/{tenant}/{env}"  → /acme/pr-42
s3          S3 key prefix                "{tenant}/{env}"   → acme/pr-42/config.json
redis       key prefix                   "{tenant}:{env}"   → acme:pr-42:vartrack
mongo       collection name              "{env}-config"     → pr-42-config
linux       full file path               "/etc/app/{env}/config.env"
helm        release name                 "app-{env}"        → app-pr-42
configmap   ConfigMap name               "myapp-{env}"      → myapp-pr-42

When not set each sink falls back to its own sink-specific config key.

Type	string
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it
Former names	zk_path_template — still read, with a warning

variables_map

Renames of flat keys before they are written: {"NEW_NAME": "path.in.file"} writes the value at path.in.file under NEW_NAME.

Type	object (string → string)
Set in	config.cue, bundle.json, vartrack.json
Across layers	merged key by key

sync_mode

How a sync writes. AUTO (the default) uses GIT_UPSERT_ALL for a file of up to 500 keys and GIT_SMART_REPAIR above. GIT_UPSERT_ALL writes every key. GIT_SMART_REPAIR reads what the sink holds and writes only what differs, by content: the changed keys in Redis, ZooKeeper and MongoDB key-value, and in a sink that holds the file as one object (a MongoDB document, an S3 object, a file, a ConfigMap, a Helm values file or release) the whole file, or nothing when it already holds the file. If the sink cannot be read, every key is written. The proto names (SYNC_MODE_AUTO, ...) are read too. Any other value is refused.

Type	string: AUTO, GIT_UPSERT_ALL, GIT_SMART_REPAIR
Set in	config.cue, bundle.json, vartrack.json
Across layers	the upper layer replaces it

exclude_repositories

Repositories (glob patterns) this rule skips although repositories matches them.

Type	list
Set in	config.cue
Across layers	only config.cue sets it

overrides

Turns the rule on or off for some repositories: [{match_repositories: ["other-org/*"], enable: true}].

Type	list
Set in	config.cue
Across layers	only config.cue sets it

prune

Delete keys varTrack wrote before that Git no longer holds: true, or {enabled, protection}. Prune runs once per environment after all its files are written, only on sinks that keep each key separately (Redis, ZooKeeper, MongoDB with STRATEGY_KEY_VALUE). A key changed outside varTrack is kept and reported. protection lists glob patterns of keys that are never deleted; every layer's patterns add up. An object with only protection does not turn pruning on.

Type	boolean, or object (enabled, protection)
Set in	config.cue, bundle.json, vartrack.json
Across layers	merged key by key; protection patterns add up

self_heal

The watcher compares the datasource with Git on every poll and, on drift, has the orchestrator write Git's values back.

Type	boolean
Set in	config.cue
Across layers	only config.cue sets it

force

Rule keys pinned by this bundle. The orchestrator builds the rule it syncs with in layers, each overriding the one before: this rule, the schema repo's bundle.json rule for the same platform and datasource, the repo's vartrack.json, and last these keys, e.g. force: {prune: {enabled: false}}. Keys only the bundle sets (connection settings, secrets, repositories, self_heal, ...) are not needed here and are ignored.

Type	object
Set in	config.cue
Across layers	only config.cue sets it

tenants

The tenants whose bundle.json may layer this rule: any tenant when empty. When no tenant's bundle.json names the rule, the first one owns it ("default" when empty).

Type	list
Set in	config.cue
Across layers	only config.cue sets it

suspend

Pauses automatic syncs: pushes and self-heal skip the rule, while syncs started by hand (web UI, vt) still run, so a pause does not block a deliberate sync.

Type	boolean
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

drift_ignore

Keys (glob patterns) a drift check does not compare: keys the application changes itself.

Type	list
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

strict_validation

A file the CUE schema rejects fails the sync instead of being written with a warning. Without it a failed validation is logged and the file is still synced.

Type	boolean
Set in	config.cue, bundle.json, vartrack.json
Across layers	the upper layer replaces it

schema_map

Which schema checks which file, by the file's path in its repository: the first entry whose match matches the path wins. Without a match the schema is found by the file's name (<name>.cue, then default.cue) as before. A schema the map names that is not in the schema repository fails the file, with or without strict_validation. The layers add up, config.cue's entries first, so a path the operator mapped cannot be remapped by a tenant.

Type	list
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

schema_from_file

Let a JSON, YAML or TOML file name its own schema with a top-level $schema key, when no schema_map entry matched its path (the map wins, and the file's result says so). The value has the syntax of a schema_map schema; a URL (an editor's hint) is ignored. $schema is never synced as a key, whether this is on or not.

Type	boolean
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

repo_url

HTTPS clone URL of the config repository. Left out, it is derived from the platform and the rule's only repository.

Type	string
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

key_format

How a nested key is flattened into a flat destination key: "dot", "flat", …

Type	string
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

file_format

Linux server: the format the file is written in. Left out, the file's extension.

Type	string
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

env_as_filename

Linux server: one file per environment, named after it. True when left out.

Type	boolean
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

helm_values_mode

Helm: how values reach the chart, "set" (--set flags) or "file".

Type	string
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

s3_object_tags

S3: tags put on every object written.

Type	object (string → string)
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it

s3_tag_keys

S3: keys whose values become object tags.

Type	list
Set in	config.cue, bundle.json
Across layers	the upper layer replaces it