docs/generated/lvcs-toml.mdgenerated from code

Use · 10 min read

lvcs.toml

Every lvcs.toml section and key.

On this page
[limits][secrets][telemetry][public][protect][plugins][plugins.actions]

The lvcs.toml sections the daemon reads (discussion:owner/127). Every section is a table whose missing keys keep their defaults, so an absent file or section is the protocol defaults. lvcs.toml is a protected path (DEFAULT_PROTECTED), so a change to it is not materialized until approved (discussion:owner/122), and no peer changes the [limits] every signer is metered by alone (discussion:owner/146). [protect] (ProtectConfig, discussion:owner/378) names the files that join the protected paths besides the defaults.

[limits]

The limits in force (discussion:owner/146).

They are the limit constants in docs/generated/vocabulary.md by default (Limits::DEFAULT), each replaced by its key in protected lvcs.toml [limits] (the daemon's LvcsToml; a missing key keeps its default), so a peer can't change them by editing the file. The field names are the [limits] keys (the constants' names in lower case). They are the defaults for every signer, the owner included: each signer's Rate comes from them (Limits::sign_rate, Limits::gossip_rate), each per-second rate and the signing burst replaced by the signer's grant terms where they name one (discussion:owner/146), and the gossip machine sizes its memory and tolerance by gossip_burst. A change quota is never a limit: a grant's terms carry it (discussion:owner/70).

KeyTypeMeaning
peer_sign_per_secintegerPEER_SIGN_PER_SEC in force.
peer_sign_burstintegerPEER_SIGN_BURST in force.
peer_gossip_per_secintegerPEER_GOSSIP_PER_SEC in force.
gossip_burstintegerGOSSIP_BURST in force.

[secrets]

lvcs.toml [secrets] (discussion:owner/37), part of the daemon's LvcsToml: exempt lists paths the scan skips (tests/fixtures/**), and never_sync paths never read into documents beyond DEFAULT_NEVER_SYNC and .gitignore, both gitignore syntax relative to the tree's root. A missing key is empty.

KeyTypeMeaning
exemptarray of stringThe paths the secret scan skips, in gitignore syntax.
never_syncarray of stringThe paths never read into documents, in gitignore syntax.

[telemetry]

lvcs.toml [telemetry] (discussion:owner/71): subtrees, the directory prefixes the subtree attribute may name (at most SUBTREE_CAP); entries past the cap are ignored, so the attribute stays bounded whatever the file says.

KeyTypeMeaning
subtreesarray of stringThe directory prefixes the subtree attribute may name.

[public]

lvcs.toml [public] (discussion:owner/487): machines, whether an anonymous reader may read node.load, off by default. Read at approved heads like every section.

KeyTypeMeaning
machinesbooleanWhether anyone may read each node's load.
ledgersarray of stringThe plugin ledgers an anonymous reader may read, as gitignore-syntax lines over .lvcs/x/** (discussion:owner/567), in place of each plugin manifest's public_ledgers; None keeps the manifests'. Never a private plugin's (the secrets plugin's): a list covering .lvcs/x/secrets/ is refused.

[protect]

lvcs.toml [protect] (discussion:owner/378): paths, gitignore lines, ASCII case-insensitive, of the files that join the protected paths besides DEFAULT_PROTECTED: what an action's scripts call or read, which core can't see (discussion:owner/532). Read only at approved heads, like every section, and lvcs.toml is protected, so only an approval changes it.

KeyTypeMeaning
pathsarray of stringThe lines.

[plugins]

[plugins]: each plugin's settings, inline or a path to its own toml, which is protected like this file (discussion:owner/514).

Type: crate::plugin::config::PluginsConfig.

[plugins.actions]

[plugins.actions] as written.

KeyTypeMeaning
actionsarray of ActionEntryThe [[actions]] entries.
channelsChannelsTableEach combination's members (discussion:owner/297).
runnerRunnerTableA change runner's quiet period (discussion:owner/127).
githubWorkflowsTableHow the GitHub workflows map (discussion:owner/245), the github sub-plugin's table.
varsVarsValues a trigger's if reads as vars.<name> (discussion:owner/627).

[[plugins.actions.actions]]

One [[actions]] entry of lvcs.toml as written (discussion:owner/245).

name is [a-z0-9._-]+, unique in the file, and names the channel the action moves (discussion:owner/297). An action whose on is not change is gated: it takes only frontiers every one of its after channels already holds. on is its trigger: change (the default: it runs when main goes quiet after a change, and moves its channel at each frontier it passes with quorum); { channel = "<name>" } (a gated action: it runs when that channel, any action's or a [channels] combination, moves to a new frontier, against that frontier); or manual (a gated action that runs only on a run request of its own channel, lvcs run). after is one channel or a list of them, each an action's channel or a combination: for a channel trigger, that channel (the default) or ones upstream of it along after links and combination members; for a manual action, the change set (every change action's channel but the generator's, the default, written out). A trigger or after naming no known channel, and triggers, after links, and combination members that form a cycle, are refused. paths and uses are gitignore-syntax patterns; paths may be left out only by the generator. run is the argument list of the action's one step (no shell); steps lists its steps instead (discussion:owner/248), and exactly one of the two is given. env sets variables for every step, each value a template (${{ secrets.<NAME> }} in a gated action naming one of its secrets). toolchain names values of the bounded toolchain vocabulary the action needs, and a node step adds node. writes names the derived files a change action generates: at most one action has it, and with no paths its inputs are every synced file that isn't derived. secrets names the credential variables a run copies from its runner's environment, never their values; only a gated action has them, since any code on main runs in a change action's sandbox (secret_in_change, refused at parse and at approve). quorum raises the attestations or outcomes the action needs above QUORUM_DEFAULT, and a gated action's above QUORUM_PROTECTED. timeout_secs can only lower the class bound (CHECK_TIMEOUT_SECS for a change action, GATED_TIMEOUT_SECS for a gated action). image runs every step in that OCI image's root instead of the runner's own system directories (discussion:owner/346): <name>@sha256:<digest>, pinned by digest, a tag alone refused (image_unpinned); an action with image takes no toolchain, and the generator takes no image yet. Any other key is refused at parse. requires names the labels a runner must hold to claim a run (discussion:owner/648), at most ACTION_REQUIRES_MAX, each [a-z0-9][a-z0-9-]{0,31}, on change and gated actions alike. queue is how its runs wait (discussion:owner/673): latest (one under way, the newest asked waiting) or all (every frontier runs); latest by default for every action, change checks included, and all opt-in (discussion:owner/677).

KeyTypeMeaning
namestringThe action's name.
onOnWhat runs it; change by default.
afterAfterThe channels a gated action's frontier must already be held by; the trigger channel, or the change set for a manual action, by default.
pathsarray of stringThe paths it covers, in gitignore syntax.
usesarray of stringThe further paths it reads, in gitignore syntax; empty by default.
runarray of stringIts one step's argument list, when steps is not given.
stepsarray of StepEntryIts steps, when run is not given (discussion:owner/248).
envtable of stringThe variables every step runs with, each value a template.
toolchainarray of stringThe toolchains it needs, values of the toolchain vocabulary.
writesarray of stringThe derived paths it generates, in gitignore syntax; empty by default.
secretsarray of stringThe credential variable names a gated action's run receives; empty by default.
quorumintegerThe attestations or outcomes it needs, when above its floor.
timeout_secsintegerIts wall clock and CPU limit, when below its class bound.
imagestringThe OCI image its steps run in, pinned by digest (discussion:owner/346).
requiresarray of stringThe labels a runner must hold to claim its runs (discussion:owner/648); none by default.

plugins.actions.actions.on values

An [[actions]] entry's on: "change", "manual", { channel = "<name>" }, or { event = "<kind>" or "channel/<name>", if? = "<CEL>" } (discussion:owner/522 to 524; { channel = … } goes with core's runner).

FormMeaning
ChangeIt runs when main goes quiet after a change.
Channel(String)It runs when the named channel moves to a new frontier.
ManualIt runs on a run request of its own channel.
Event {It runs on each durable event of kind event that cond (a CEL expression, discussion:owner/524) matches; channel/<name> is that channel's moves.
event: StringThe kind, or channel/<name>.
cond: Option<String>The if, when one is written.
}-

plugins.actions.actions.after values

An [[actions]] entry's after as written: one channel name, or a list of them. after = "tests" and after = ["tests"] map to one value (discussion:owner/297).

FormMeaning
stringOne channel.
array of stringA list of channels.

[[plugins.actions.actions.steps]]

One [[actions.steps]] entry (discussion:owner/248): exactly one of run (an argument list, no shell), script (text run by shell: bash, sh, python, or a custom command line holding {0}; bash -e {0}, or sh -e {0} without bash, when unset), and node (a directory of the action's inputs holding main, and optionally pre and post, each run with node, its inputs given by with).

id names it for ${{ steps.<id>.outputs.<name> }}; if is success() (the default), always(), failure(), cancelled(), or a step output; env is set after the action's and earlier steps' GITHUB_ENV; working_directory is relative to /work; continue_on_error lets it fail without failing the run; and timeout_secs can only lower what is left of the action's limit. script, env, and with values are templates. Any other key is refused at parse.

KeyTypeMeaning
idstringIts id.
ifstringIts if.
envtable of stringIts environment.
working_directorystringIts working directory, relative to /work.
continue_on_errorbooleanWhether its failure leaves the run passing.
timeout_secsintegerIts own limit, in seconds.
runarray of stringAn argument list.
scriptstringA script's text.
shellstringThe script's shell.
nodestringA node program's directory.
mainstringThe node program, in node.
prestringThe node program run first, in node.
poststringThe node program run last, in node.
withtable of stringThe node program's inputs.

[plugins.actions.runner]

[runner] (discussion:owner/161 and discussion:owner/245): how long main's visible frontier must be unchanged before a runner serving change channels prepares a job for it.

quiet_ms can only raise QUIET_MS, up to QUIET_MAX_MS: a smaller value counts as QUIET_MS and a larger one as QUIET_MAX_MS. It defaults to QUIET_MS. Any other key is refused at parse.

KeyTypeMeaning
quiet_msintegerThe quiet period asked for, in milliseconds.

[plugins.actions.github]

lvcs.toml's [workflows] (discussion:owner/245): skip, the action names (<file stem>/<job id>, every cell of the job, or one cell's full name) left out deliberately; inputs, an action's narrowed inputs by name (**, every synced file, when unset); vars, the vars context; and repository, owner/name for github.repository. Any other key is refused at parse.

KeyTypeMeaning
skiparray of stringAction names left out.
inputstable of InputsEntryNarrowed inputs, by action name.
varstable of stringThe vars context.
repositorystringgithub.repository.

[plugins.actions.github.inputs.<name>]

One [workflows] inputs."<name>" entry: gitignore-syntax patterns.

KeyTypeMeaning
pathsarray of stringThe paths the action covers.
usesarray of stringThe paths it reads besides.