werkrevisor/docs/prs/2026-10-18-PR#124-release-host-config.md

PR#124: The Release Brings the Host Configs in Line

Version: minor

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

Related Links

• werkrevisor PR#118: Werkator releases werkrevisor after each merge.
• werkrevisor PR#117: removed [doc_check] model and provider_order.
• werkrevisor PR#101: tools/sync-host-config.

Problem

The release build installs the archive with the new code, but leaves the host configs as they are: the inline WERKREVISOR_CONFIG_TOML in ~/<repo>/.git/werkator/.werkator.yml of each repository on mih09.

On 2026-10-18 this broke every werkrevisor review. PR#117 removed two keys of [doc_check] from the parser and from config/werkrevisor.toml, but the host block kept them, and the strict parser of 0.49.0 rejected them as unknown keys. The human fixed it with tools/sync-host-config --apply.

Non-Goals

• No change of tools/sync-host-config; it stays the way to check or sync by hand.
• No check of the other parts of a machine config, e.g. the environment or the secrets.

Specification

Feature: the release installs the host config of main with the archive

Scenario#124.01: a stale host key is replaced with the archive

… so that the new code never runs with a host config that only the old code accepts.

• Given the host config on mih09 has an old setting that the new version no longer knows
• And config/<repo>.toml does not have this setting
• When the release build installs the new version
• Then the host config on mih09 equals config/<repo>.toml
• And the machine config uses the new archive
• And the backup holds the old host config
• And the output names the setting, but not its value

Verified by

• test_release_rootfs.ReleaseRootfsTest.test_a_stale_host_key_is_replaced_with_the_archive

Scenario#124.02: a host setting that the file would lose stops the release

… so that the release never reverts a setting that the operator made on the host alone.

• Given a host block with a known key that config/<repo>.toml lacks or sets to another value
• When the release build runs
• Then it fails, names the repository and the key, never a value, and changes no machine config, also not of the other repositories, and assembles no archive

Verified by

• test_release_rootfs.ReleaseRootfsTest.test_a_host_setting_that_the_file_would_lose_stops_the_release
• test_release_rootfs.ReleaseRootfsTest.test_a_host_block_changed_after_the_check_stops_the_install
• test_release_rootfs.ReleaseRootfsTest.test_an_equal_host_block_changed_after_the_check_stops_the_install

Scenario#124.03: a host config that cannot be checked stops the release

… so that a machine config without a known source is not released blindly.

• Given a machine config that names a werkrevisor archive, and has no single WERKREVISOR_CONFIG_TOML block or no config/<repo>.toml, or the file fails the new parser
• When the release build runs
• Then it fails, names the repository and the cause, and changes no machine config

Verified by

• test_release_rootfs.ReleaseRootfsTest.test_a_host_config_that_cannot_be_checked_stops_the_release

Solution

• tools/release_rootfs.py release checks the host configs after "already released" and before it assembles. Per machine config that names a werkrevisor archive, it reads config/<repo>.toml with load_host_config of the new version, the way a review reads WERKREVISOR_CONFIG_TOML. It does not check the values: they need the .werkrevisor.toml of the repository, which the release does not have; the tests of config/ check them.
• It finds the block with tools/host_config_block.py, as tools/sync-host-config does, and compares the keys. A key that differs and that the new version still knows stops the release; a key it no longer knows is dropped. It checks all machine configs before it fails, so one run names all problems.
• install compares each host block with the checked one before it writes any machine config, and again at its write; a block that the operator changed while the archive was assembled stops the install, also a block that was equal.
• install writes the new block and the new archive name in one replacement of the machine config; the backup .bak-before-<version> is the one it already made. It prints the changed lines with difflib, since a new block may change the number of lines.
• install imports neither host_config_block nor werkrevisor.config at the start: tools/deploy-rootfs sends release_rootfs.py alone to the host. The manual way through tools/deploy-rootfs thus still leaves the host configs to tools/sync-host-config.
• The output names repositories, keys and line numbers, never a value of the host block. An invalid host block shows only its line, as in load_host_config.
• README and the operations document describe the transfer by the release.
• Version 0.55.0; main holds 0.54.1.

Before the merge

The first release after the merge checks every host block on mih09, and a host setting that the file lacks stops it. On 2026-10-20 tools/sync-host-config showed no such key; werkator and werkcrappit differed only by keys of the file, which this PR removes (see "Additional Changes").

Release Notes

• The release build installs config/<repo>.toml as the host config of each repository, together with the archive. It stops before any change if the host holds a setting that the file would lose.

Open Questions

• Should the release refuse a differing host block, or write config/<repo>.toml into it? It writes the file, in the same write that names the new archive; the human chose this on 2026-10-18. A refusal would leave the human a trap: after a manual tools/sync-host-config --apply, the old code runs with the new config until the release runs again, and fails if the new version added a key. One write switches code and config together, and the backup .bak-before-<version> restores both. It refuses only where writing would lose a host setting that the new parser still accepts: the operator may switch e.g. the model on the host alone.
• config/werkator.toml and config/werkcrappit.toml hold keys that their host blocks lack; may the release add them? No, the files now hold only the host part, as the host blocks on mih09; the human decided on 2026-10-20. The extra keys repeat the .werkrevisor.toml of each repository, and [review] extra_instructions is appended, so the release would have put these instructions twice into the prompt. tools/sync-host-config on 2026-10-20 showed no other difference, so the first release changes no host block.

Additional Changes

• config/werkator.toml, config/werkcrappit.toml and config/werkdock.toml hold only the host part, like config/werkrevisor.toml. Their tests read the repository part from copies of the .werkrevisor.toml of these repositories in tests/fixtures/.
• werkdock came with PR#126 and its complete file; the human decided on 2026-10-20 to trim it too. Its host block on mih09 held the whole file, so the instructions stood twice in the prompt; the human replaced it with the trimmed file by tools/sync-host-config --apply on 2026-10-20.