`versionx.toml`

Generated from crates/versionx-config/src/schema.rs. Edit the schema there and re-run cargo xtask docs to update this page.

versionx.toml is the primary configuration file. One lives at the root of every repo that uses Versionx. Unknown top-level keys are rejected so typos get caught.

`VersionxConfig`

The root of versionx.toml.

Unknown top-level keys are not forwarded to extra — we fail loudly so typos get caught.

Field	Type	Serde	Description
`versionx`	`VersionxMetaConfig`	optional	Top-level metadata.
`vars`	`IndexMap < String , String >`	optional	Environment variables exported into every adapter/task invocation.
`runtimes`	`RuntimesConfig`	optional	Runtime pins (node, python, rust, pnpm, etc.).
`ecosystems`	`IndexMap < String , EcosystemConfig >`	optional	Per-ecosystem configuration.
`tasks`	`IndexMap < String , TaskConfig >`	optional	Native task definitions. v1.0 ships topo-exec without caching.
`release`	`Option < ReleaseConfig >`	optional	Release orchestration settings.
`links`	`IndexMap < String , LinkConfig >`	optional	External-repo links (submodule / subtree / virtual / ref).
`policies`	`Option < PoliciesConfig >`	optional	Policies referenced by this repo.
`github`	`Option < GitHubConfig >`	optional	GitHub integration (non-App — used by reusable Actions).
`inherit`	`Option < InheritPolicy >`	optional	Inheritance semantics for array-valued keys.
`advanced`	`AdvancedConfig`	optional	Advanced / rarely-touched knobs.
`components`	`Vec < ComponentConfig >`	rename: `components`, optional	`[[components]]` — hand-declared components that aren't covered by native manifests (protocol schemas, shared asset bundles, docs sites, etc.). Discovery merges these on top of auto-detected components.

`VersionxMetaConfig`

[versionx] block: project metadata.

Field	Type	Serde	Description
`schema_version`	`Option < String >`	optional	Schema version. Required at L3+. Defaults to [`SUPPORTED_SCHEMA_VERSION`] when absent.
`name`	`Option < String >`	optional	Human-readable project name. Defaults to the containing dir.
`workspace`	`bool`	optional	When `true`, this file is a workspace root and `vx` walks up to it.

`RuntimesConfig`

[runtimes] block.

Cannot set deny_unknown_fields here because tools is flattened — every tool name (node, python, pnpm, ...) appears as a top-level key and serde would reject them all.

Field	Type	Serde	Default	Description
`providers`	`RuntimeProviders`	optional		Provider URLs / names per tool. Optional.
`tools`	`IndexMap < String , RuntimeSpec >`	flatten		Tool -> version spec. Captures everything not matched above. Values may be a plain string (`"22.12.0"`) or a table with distribution hints (`\{ version = "21", distribution = "temurin" \}`).

`RuntimeProviders`

[runtimes.providers] — where to fetch installers from.

Same flatten caveat as [RuntimesConfig]: no deny_unknown_fields.

Field	Type	Serde	Default	Description
`providers`	`BTreeMap < String , String >`	flatten		Tool -> provider string (URL or named provider like `"python-build-standalone"`, `"nodejs.org"`, `"temurin"`).

`RuntimeSpec` (enum)

A runtime spec — either a plain version string or a structured table.

Variant	Description
`Version`	`node = "22.12.0"` or `node = "lts"`
`Detailed`	`jvm = \{ version = "21", distribution = "temurin" \}`

`EcosystemConfig`

[ecosystems.<id>] block.

Field	Type	Serde	Description
`package_manager`	`Option < String >`	optional	`"pnpm"`, `"uv"`, `"cargo"`, etc. Auto-detected when absent.
`root`	`Option < Utf8PathBuf >`	optional	Path (relative to this file) where the ecosystem's manifest lives. Defaults to the repo root.
`workspaces`	`Vec < String >`	optional	Workspace member globs (Node pnpm workspaces, Cargo workspaces, uv workspaces).
`venv_manager`	`Option < String >`	optional	Python-specific: which tool owns venv creation (`"uv"` / `"poetry"` / `"versionx"`).

`TaskConfig`

[tasks.<name>] block. Full schema lands with the task runner (0.9).

Field	Type	Serde	Description
`run`	`String`		Shell-free command (run via `versionx::proc`, never invoking a shell).
`env`	`IndexMap < String , String >`	optional	Task-level env overrides.
`depends_on`	`Vec < String >`	optional	Upstream tasks that must succeed first.
`inputs`	`Vec < String >`	optional	Input globs (feed into the v1.2 content-addressed cache).
`outputs`	`Vec < String >`	optional	Output globs (ditto).

`ReleaseConfig`

[release] block.

Field	Type	Serde	Default	Description
`strategy`	`String`		default_strategy	`"pr-title"` (default), `"conventional"`, `"changesets"`, `"manual"`.
`ai_assist`	`String`		default_ai_assist	`"mcp"` (agent drives), `"byo-api"`, or `"off"`.
`versioning`	`String`		default_versioning	`"semver"` or `"calver"`.
`tag_template`	`String`		default_tag_template	Template for the git tag name. `\{version\}` and `\{package\}` supported.
`changelog`	`String`		default_changelog	Path to the changelog file relative to the repo root.
`plan_ttl`	`String`		default_plan_ttl	Plan TTL (human duration: `"1h"`, `"24h"`, `"7d"`).
`push_mode`	`String`		default_push_mode	`"prompt"` (default, TTY-only) or `"explicit"` (always require flag).
`ai`	`Option < AiConfig >`	optional		BYO-API-key LLM provider config, only consulted when `ai_assist = "byo-api"`.
`packages`	`IndexMap < String , PackageReleaseConfig >`	optional		Per-package overrides (paths and bump rules).
`groups`	`Vec < ReleaseGroupConfig >`	optional		`[[release.groups]]` — named sets of components that should be versioned + tagged together (e.g. an SDK + its CLI that always ship at the same version). Groups are consulted by the bump planner when deciding what to include in a single plan.

`ComponentConfig`

[[components]] entry.

Hand-declared component for non-manifest artifacts (protocol files, shared asset bundles, docs sites, etc.). Works alongside auto-discovery via versionx-workspace — declared entries win when names collide.

Field	Type	Serde	Description
`name`	`String`		Stable identifier. Referenced by `depends_on` and `[[release.groups]]`.
`path`	`String`		Directory rooted at the workspace, e.g. `"protocols/chat"`.
`kind`	`Option < String >`	optional	Optional kind label: `"node" \| "python" \| "rust" \| "go" \| "ruby" \| "jvm" \| "oci"` or a custom string (e.g. `"proto"`).
`version`	`Option < String >`	optional	Optional current version (`"1.2.3"`). Missing means "not versioned yet".
`inputs`	`Vec < String >`	optional	File globs that define the component's content-hash inputs. Defaults to `["*/"]` when empty.
`depends_on`	`Vec < String >`	optional	IDs of other components this depends on. These are intra-workspace edges, not package-manager dependencies.

`ReleaseGroupConfig`

[[release.groups]] entry — a lockstep bundle.

When any member of a group gets bumped, every member is bumped to the same version. Useful for tightly-coupled SDK/CLI pairs.

Field	Type	Serde	Default	Description
`name`	`String`			Human-readable group name — used in plan summaries + tag templates.
`members`	`Vec < String >`			Component IDs that share a version. Must all resolve.
`mode`	`String`		default_group_mode	`"lockstep"` (default, all members get the same version) or `"independent"` (members share a plan but keep independent versions).
`tag_template`	`Option < String >`	optional		Optional tag template override. `\{version\}` supported.

`AiConfig`

[release.ai.byo] — headless LLM config.

Field	Type	Serde	Description
`provider`	`String`		`"anthropic"`, `"openai"`, `"gemini"`, `"ollama"`.
`model`	`String`		Model name (`"claude-sonnet-4-6"`, `"gpt-4o"`, `"llama3.2"`, etc.).
`api_key_env`	`Option < String >`	optional	Env var to read the API key from.
`endpoint_env`	`Option < String >`	optional	Optional endpoint override for self-hosted / proxied servers.

`PackageReleaseConfig`

Per-package release knobs inside a monorepo.

Field	Type	Serde
`public`	`bool`	optional
`registry`	`Option < String >`	optional
`paths`	`Vec < String >`	optional

`LinkConfig`

[links.<name>] block.

Field	Type	Serde	Description
`kind`	`String`	rename: `type`	`"submodule"` \| `"subtree"` \| `"virtual"` \| `"ref"`.
`path`	`Option < Utf8PathBuf >`	optional
`url`	`String`
`track`	`Option < String >`	optional
`update`	`Option < String >`	optional
`bidirectional`	`bool`	optional
`squash`	`bool`	optional

`PoliciesConfig`

[policies] block.

Field	Type	Serde	Default	Description
`inherit`	`Vec < String >`	optional
`files`	`Vec < String >`	optional

`GitHubConfig`

[github] block.

Field	Type	Serde
`owner`	`Option < String >`	optional
`repo`	`Option < String >`	optional
`required_checks`	`Vec < String >`	optional

`InheritPolicy`

[inherit] block — controls array merge semantics.

Field	Type	Serde	Default	Description
`append`	`Vec < String >`	optional		Keys whose arrays are concatenated across levels instead of replaced.

`AdvancedConfig`

[advanced] block.

Field	Type	Serde	Description
`daemon`	`Option < String >`	optional	`"auto"` \| `"always"` \| `"never"`. Default: `"auto"`.
`jobs`	`Option < usize >`	optional	Max parallelism for adapter operations (0 = auto).
`state_backend`	`Option < String >`	optional	Remote state backend URL (post-v1.0).
`state_backend_env`	`Option < String >`	optional	Env var that holds the remote-state URL (preferred over inline).
`lockfile`	`Option < bool >`	optional	Disable the lockfile entirely (not recommended).

`OutputOverride` (enum)

Hint type for the CLI --output flag when it's persisted into config.

Variant	Description
`Human`
`Json`
`Ndjson`

VersionxConfig​

VersionxMetaConfig​

RuntimesConfig​

RuntimeProviders​

RuntimeSpec (enum)​

EcosystemConfig​

TaskConfig​

ReleaseConfig​

ComponentConfig​

ReleaseGroupConfig​

AiConfig​

PackageReleaseConfig​

LinkConfig​

PoliciesConfig​

GitHubConfig​

InheritPolicy​

AdvancedConfig​

OutputOverride (enum)​

See also​