werkrevisor/docs/prs/2026-10-17-PR#118-release-build.md

PR#118: Werkator Releases werkrevisor After Each Merge

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#115: tools/build-rootfs with Podman.

Problem

A merge to main does not reach mih09. The human builds the rootfs archive on the workstation with tools/build-rootfs and distributes it with tools/deploy-rootfs; until then, the reviews run the old version. mih09 has neither Docker nor Podman, so Werkator cannot run tools/build-rootfs there.

Non-Goals

• No automatic release of the statistics service.
• No automatic update of the PR-Agent base image; a new base image stays a manual step.

Specification

Feature: a merge to main releases werkrevisor

Scenario#118.01: a new version is assembled and installed

… so that the reviews run the merged code without a manual step.

• Given main at a version whose archive does not exist yet, and the base archive of the pinned PR-Agent image
• When the release build runs after the green build of main
• Then the archive of the version holds the base archive plus werkrevisor/werkrevisor/ and werkrevisor/config/, and each machine config that named a werkrevisor archive names the new one

Verified by

• test_release_rootfs.ReleaseRootfsTest.test_a_new_version_is_assembled_and_installed

Scenario#118.02: a released version is not released again

… so that a repeated build changes nothing.

• Given every machine config names the archive of the current version
• When the release build runs
• Then it builds nothing, changes no machine config and succeeds

Verified by

• test_release_rootfs.ReleaseRootfsTest.test_a_released_version_is_not_released_again

Scenario#118.03: a missing base archive fails the release

… so that a new PR-Agent image is not released with the files of the old one.

• Given the base archive of the PR-Agent image named in the Dockerfile is missing
• When the release build runs
• Then it fails, names the missing archive and the command that creates it, and changes no machine config

Verified by

• test_release_rootfs.ReleaseRootfsTest.test_a_missing_base_archive_fails_the_release

Scenario#118.04: a machine config without a werkrevisor archive stays unchanged

… so that a repository without werkrevisor reviews does not get one.

• Given a machine config that names no werkrevisor archive
• When the release build installs a new version
• Then that machine config is unchanged and has no backup

Verified by

• test_release_rootfs.ReleaseRootfsTest.test_a_machine_config_without_a_werkrevisor_archive_stays_unchanged

Solution

• tools/release_rootfs.py release is the build command of the new build release in .werkator.yml. It reads the version and assembles werkrevisor-rootfs-<version>.tar.zst with Python's tarfile: the base archive pr-agent-rootfs-<digest>.tar.zst, plus /work, werkrevisor/werkrevisor/ and werkrevisor/config/, owned by root, without __pycache__. Its file list equals the one of the archive 0.44.1, plus /work, the WORKDIR of the Dockerfile: the Docker build of 0.43.0 holds it, the Podman build of 0.44.1 does not. The reviews run in the worktree and do not use /work; the archive holds it so that it matches the Dockerfile.
• It compresses with compression.zstd, part of the standard library since Python 3.14 (PEP 784), else with the zstd program; mih09 has Python 3.11.
• It replaces each machine config through a temporary file with the same mode, so Werkator never reads half of one.
• It refuses to install if a machine config names a werkrevisor archive in another directory, since only the name of the archive changes.
• The base archive carries the first 12 hex digits of the digest in the Dockerfile; a new PR-Agent image needs a new base archive, which tools/build-rootfs --base creates on the workstation.
• tools/release_rootfs.py install replaces the remote script of tools/deploy-rootfs, so both ways install alike. Without repositories it takes each machine config that names a werkrevisor archive, and the release build takes the directory of these archives; so no list of repositories needs care.
• The trigger afterSuccessOf: default on main and the native runtime are the host's part, pinned by Werkator. The build runs outside the sandbox, since the sandbox sees neither the machine configs nor /home/storage.
• .werkrevisor.toml lets Jev judge tools/deploy-rootfs and tools/release_rootfs.py like tools/build-rootfs.
• README, operations document and AGENTS.md describe the release build.
• Version 0.46.0; PR#117 holds 0.45.0.

Setup on mih09 after the merge

1. Copy pr-agent-rootfs-7d98954c2928.tar.zst to /home/storage/mih09/users/werkator/.
2. Add the host part of release to ~/werkrevisor/.git/werkator/.werkator.yml, as in the README.
3. Check that the release build of the merge commit installs 0.46.0.

Open Questions

None.

Follow-up PRs

• Once werkdock builds images, the release build may build from the Dockerfile and drop the base archive.