Skip to content

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 ​

keytyperequiredmeaning
profilestringoptionalNamed 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.
releaseReleaseConfigoptional—
publishPublishConfigoptional—

[release] ​

keytyperequiredmeaning
unitsUnitsSpecoptionalHow release units resolve. Default: cargo workspace at root.
tag_formatstringoptionalDefault tag template for units that don't override it.
changelog_pathstringoptionalChangelog file spliced per unit — resolved relative to each unit's path (crates/foo + CHANGES.md → crates/foo/CHANGES.md).
styleguidestringoptionalkeep-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).
strategyStrategyRefoptionalRelease 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_bumpBumpoptionalRepo-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_excludelistoptionalPath 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_overridesBTreeMap<String, UnitOverride>optionalPer-unit overrides keyed by unit name.
sync_refsSyncRefsConfigoptionalPack-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.

toml
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 bump across 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). fallback applies when inference finds nothing; release.default_bump fills 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-CommitKind types are nameable.
  • Each absent strategy.* sub-table defaults to the conventional rules, 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), and keep-a-changelog (the keepachangelog.com section layout — see below).
  • The resolved strategy echoes on plan results as plan.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:

sectioncommits
### Addedfeat
### Changedrefactor, plus breaking commits of types with no section of their own (chore!, deps!, unknown ! types)
### Deprecateddeprecate, deprecation
### Removedrevert, remove
### Fixedfix, perf
### Securitysecurity

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>] ​

keytyperequiredmeaning
bumpBumpoptionalForce this unit's bump (beats inference).
tag_formatstringoptionalPer-unit tag template.
publishVec<PublishTarget>optionalRestrict publish targets ("crates-io", "github-release").
skipbooloptionalSkip this unit entirely (e.g. a lib that versions with its parent).

[release.sync_refs] ​

keytyperequiredmeaning
rulesVec<SyncRefRule>optionalRewrite rules, applied in order. Empty = the stage is disabled entirely (no files touched, no step reported).

sync rule (rules[] entries) ​

keytyperequiredmeaning
fileslistoptionalRepo-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.
findstringrequiredRegex matching the stale ref. Required.
replacestringrequiredLiteral 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.

toml
[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 → new pair. A plan whose releasing units disagree on new_version (or current_version) reports status:"skipped" and the release proceeds unsynced — the shims' len(vs)==1 guard.
  • Idempotent — rules match the old version; once refs say new, nothing matches and the stage reports zero changes.
  • Dry-run — bump/release with dry_run:true (the default) reports status:"dry-run" plus changed_files without writing.
  • Results surface as sync_refs{status, reason?, old, new, changes[], changed_files?} on bump and release; steps_run gains a "sync-refs" entry between bump-manifests and commit-bump when rules are configured. Synced files are staged into the release commit itself — no separate pre-commit.

[publish] ​

keytyperequiredmeaning
cratesCratesPublishoptionalcrates.io publish target.
ghreleasesGhReleasePublishoptionalGitHub Releases publish target.
dry_runbooloptionalSchema-level dry-run flag; the serve op's dry_run param is what callers use.

[publish.crates] ​

keytyperequiredmeaning
enabledbooloptionalcrates.io publishing on/off.
retry_429booloptionalRetry crates.io 429s with backoff (release.sh semantics).
max_attemptsintoptionalMax publish attempts per unit.
token_envstringoptionalEnv 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_refstringoptionalOptional cuora://&lt;scope&gt;/&lt;name&gt; secret ref — resolved via cuora at publish time and takes precedence over token_env. The value never appears in config or logs.

[publish.ghreleases] ​

keytyperequiredmeaning
enabledbooloptionalGitHub Releases on/off.
token_envstringoptionalEnv var NAME holding the GitHub token — resolved via environment/cuora at publish time; the value never appears in config, manifests, or logs.
repostringoptionalRepo override owner/name; default = git remote.
token_refstringoptionalOptional cuora://&lt;scope&gt;/&lt;name&gt; secret ref — resolved via cuora at publish time and takes precedence over token_env. The value never appears in config or logs.
assetslistoptionalRepo-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/  >  defaults

Without 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_fields is not set on the config structs; typos surface as ignored keys, so check tarsi-serve plan output when a key seems inert.

MIT licensed — part of the 9aia GAIA stack.