tarsi.toml schema
The config document is tarsi_core::Config — TOML or YAML (tarsi.yaml/tarsi.yml preferred on discovery ties). Pure serde types in crates/tarsi-core/src/config.rs; loading/layering in tarsi-config. Secret names appear (token_env); values never do.
Top level
| key | type | required | meaning |
|---|---|---|---|
profile | string | optional | Named release profile to layer under this config — a type: tarsi tamias pack or a dir under ~/.config/tarsi/profiles/. Resolved by tarsi-config (profile dir becomes a config layer between the repo file and the user file); ignored by planning itself. |
release | ReleaseConfig | optional | — |
publish | PublishConfig | optional | — |
[release]
| key | type | required | meaning |
|---|---|---|---|
units | UnitsSpec | optional | How release units resolve. Default: cargo workspace at root. |
tag_format | string | optional | Default tag template for units that don't override it. |
changelog_path | string | optional | Changelog file spliced per unit — resolved relative to each unit's path (crates/foo + CHANGES.md → crates/foo/CHANGES.md). |
styleguide | string | optional | keep-a-changelog | conventional-commit-grouped | … Deprecated (P-030) — superseded by [ReleaseConfig::strategy]'s changelog section table. Still parsed for backward compat; has no effect on planning (it never did — the field was always descriptive). |
strategy | StrategyRef | optional | Release strategy (P-030): a builtin name ("conventional", "semantic-release-angular") or an inline rules table ([release.strategy.bump] / [release.strategy.changelog]). Absent = conventional, the pre-strategy behavior. Resolved inside tarsi-serve's plan path so every op inherits it. |
default_bump | Bump | optional | Repo-wide default bump when inference finds nothing — honored as the strategy's fallback (P-030 wired the previously-dead field; an explicit strategy.bump.fallback wins). |
diff_exclude | list | optional | Path globs excluded from commit→unit attribution (e.g. ["docs/**", "*.md"]). Wired in P-030: matching paths are stripped from each commit before attribution; a commit left with no paths is dropped entirely. |
unit_overrides | BTreeMap<String, UnitOverride> | optional | Per-unit overrides keyed by unit name. |
sync_refs | SyncRefsConfig | optional | Pack-ref/doc version sync — rewrite stale name@old / manifest version: refs in repo files before the release commit lands, so the tagged tree is self-consistent (T-039; replaces the per-repo scripts/release.sh pre-step). Empty rules = disabled — repos opt in. |
[release] strategy
The release policy as data (P-030): bump inference and changelog sectioning. Either a builtin name or an inline table — absent means conventional, the pre-strategy behavior.
strategy = "conventional" # builtin name, OR inline:
[release.strategy.bump]
fallback = "patch" # bump when no rule matches
[[release.strategy.bump.rules]]
type = "feat" # raw conventional type token; "*"/absent = any
scope = "core-*" # optional: exact or trailing-* glob
breaking = true # optional: pin the !/BREAKING CHANGE flag
not_type = ["fix"] # optional: type tokens that veto the match
bump = "minor" # major|minor|patch|none
[release.strategy.changelog]
[[release.strategy.changelog.sections]]
key = "added" # stable section id
heading = "Added" # rendered as `### Added`
[[release.strategy.changelog.sections.rules]]
type = "feat" # same matcher fields, no `bump`Semantics:
- Bump rules are max-match — a commit contributes the highest
bumpacross its matching rules; a unit folds max across its commits (semantic-release commit-analyzer's "highest release type wins" — rule order can't be gamed).fallbackapplies when inference finds nothing;release.default_bumpfills it when the strategy doesn't set one. - Changelog sections are first-match — a commit lands in the first section (table order) with a matching rule; table order is also render order. Commits matching nothing are dropped.
- Matchers run on the commit's raw type token —
deps,i18n, and other non-CommitKindtypes are nameable. - Each absent
strategy.*sub-table defaults to theconventionalrules, so[release.strategy.bump]alone keeps the conventional changelog. - Builtin names:
conventional(default — byte-identical to the pre-P-030 hardcoded policy),semantic-release-angular(the commit-analyzer angular preset as data), andkeep-a-changelog(the keepachangelog.com section layout — see below). - The resolved strategy echoes on
planresults asplan.strategy {name, resolved}(name= the builtin name or"custom").
What can't be data stays code: changelog render formats beyond section/heading/order, non-semver versioning, non-conventional commit parsing, anything needing execution (P-030 boundary).
keep-a-changelog
Keep a Changelog (keepachangelog.com) is a changelog layout, not a bump policy — the builtin keeps conventional's bump rules verbatim and swaps only the section table for the six canonical sections, in keepachangelog.com order:
| section | commits |
|---|---|
### Added | feat |
### Changed | refactor, plus breaking commits of types with no section of their own (chore!, deps!, unknown ! types) |
### Deprecated | deprecate, deprecation |
### Removed | revert, remove |
### Fixed | fix, perf |
### Security | security |
Breaking commits of section-owning types stay in their own section (fix!→Fixed, security!→Security, …) — Changed's catch-all vetoes them via not_type. Types outside the table (chore, docs, test, deps, release, …) still count for bump inference but are dropped from the changelog. KaC-named types (deprecate, revert, remove, security) are changelog-only here — they don't move the version unless default_bump fills the fallback; a repo that wants e.g. revert→patch takes the same table inline with one extra bump rule.
[release.unit_overrides.<name>]
| key | type | required | meaning |
|---|---|---|---|
bump | Bump | optional | Force this unit's bump (beats inference). |
tag_format | string | optional | Per-unit tag template. |
publish | Vec<PublishTarget> | optional | Restrict publish targets ("crates-io", "github-release"). |
skip | bool | optional | Skip this unit entirely (e.g. a lib that versions with its parent). |
[release.sync_refs]
| key | type | required | meaning |
|---|---|---|---|
rules | Vec<SyncRefRule> | optional | Rewrite rules, applied in order. Empty = the stage is disabled entirely (no files touched, no step reported). |
sync rule (rules[] entries)
| key | type | required | meaning |
|---|---|---|---|
files | list | optional | Repo-root-relative globs of files to rewrite ("libraries/myco/tamias.yaml", "README.md", ".agents/skills/myco/SKILL.md"). Non-matching globs are skipped — a repo can carry rules for files it doesn't have. |
find | string | required | Regex matching the stale ref. Required. |
replace | string | required | Literal replacement text. Required — an empty string would silently delete refs, so serde rejects a missing key. |
Rewrites stale version refs in repo files inside the bump/release pipeline — after manifests are bumped, before the release commit — so the tagged tree is self-consistent. This is the stage that replaced the per-repo scripts/release.sh plan+sed pre-step (T-039): pack tamias.yaml manifest versions and name@ver README/SKILL install examples.
[release.sync_refs]
rules = [
# pack manifest version line (line anchor needs (?m))
{ files = ["libraries/myco/tamias.yaml"],
find = "(?m)^version: \"{old}\"",
replace = "version: \"{new}\"" },
# doc refs — global, like the old `sed s|name@old|name@new|g`
{ files = ["README.md", ".agents/skills/myco/SKILL.md"],
find = "myco@{old}",
replace = "myco@{new}" },
]{old}/{new} expand to the releasing units' shared current_version/new_version. Inside find they are regex-escaped (so . stays literal); inside replace they expand literally. Patterns are not auto-bounded — app@{old} matches the [email protected] prefix of [email protected], exactly like the old sed pre-steps; add \b when a boundary is needed (regex has no look-around). Use (?m) for line anchors.
Semantics:
- Single-version only — sync needs one unambiguous
old → newpair. A plan whose releasing units disagree onnew_version(orcurrent_version) reportsstatus:"skipped"and the release proceeds unsynced — the shims'len(vs)==1guard. - Idempotent — rules match the old version; once refs say
new, nothing matches and the stage reports zero changes. - Dry-run —
bump/releasewithdry_run:true(the default) reportsstatus:"dry-run"pluschanged_fileswithout writing. - Results surface as
sync_refs{status, reason?, old, new, changes[], changed_files?}onbumpandrelease;steps_rungains a"sync-refs"entry betweenbump-manifestsandcommit-bumpwhen rules are configured. Synced files are staged into the release commit itself — no separate pre-commit.
[publish]
| key | type | required | meaning |
|---|---|---|---|
crates | CratesPublish | optional | crates.io publish target. |
ghreleases | GhReleasePublish | optional | GitHub Releases publish target. |
dry_run | bool | optional | Schema-level dry-run flag; the serve op's dry_run param is what callers use. |
[publish.crates]
| key | type | required | meaning |
|---|---|---|---|
enabled | bool | optional | crates.io publishing on/off. |
retry_429 | bool | optional | Retry crates.io 429s with backoff (release.sh semantics). |
max_attempts | int | optional | Max publish attempts per unit. |
token_env | string | optional | Env var NAME consulted for the crates.io token when token_ref is unset or misses — cargo reads CARGO_REGISTRY_TOKEN, and a resolved value is injected into the publish child's environment under that name. The value never appears in config, manifests, or logs. |
token_ref | string | optional | Optional cuora://<scope>/<name> secret ref — resolved via cuora at publish time and takes precedence over token_env. The value never appears in config or logs. |
[publish.ghreleases]
| key | type | required | meaning |
|---|---|---|---|
enabled | bool | optional | GitHub Releases on/off. |
token_env | string | optional | Env var NAME holding the GitHub token — resolved via environment/cuora at publish time; the value never appears in config, manifests, or logs. |
repo | string | optional | Repo override owner/name; default = git remote. |
token_ref | string | optional | Optional cuora://<scope>/<name> secret ref — resolved via cuora at publish time and takes precedence over token_env. The value never appears in config or logs. |
assets | list | optional | Repo-root-relative glob patterns for release assets — {unit} and {version} expand per releasing unit, e.g. ["dist/{unit}-{version}-*", "{unit}/checksums.txt"]. A pattern with no glob magic must match an existing file; magic patterns matching nothing are skipped. Empty = notes-only releases. |
bump values: "major" | "minor" | "patch" | "none". PublishTarget values: "crates-io" | "github-release".
Layering
With a profile resolved, config loads through LayeredFileSource — objects merge key-wise, later layers fill gaps:
repo tarsi.* > profile tarsi.* > ~/.config/tarsi/ > defaultsWithout a profile, discovery is first-match: $TARSI_CONFIG → ./tarsi.* → ~/.config/tarsi/. A missing profile name is a hard error; a present-but-broken tarsi.* file always errors loudly.
Example
See tarsi.toml at the repo root (dogfooding config) and libraries/9aia-release/tarsi.toml (the org profile).
Constraints
- Secret names (
token_env,token_ref) appear in config; values never do —cuora://refs resolve via cuora at publish time, env names resolve through the environment. - Unknown fields are not rejected at this layer —
deny_unknown_fieldsis not set on the config structs; typos surface as ignored keys, so checktarsi-serveplan output when a key seems inert.