ansible-role-seriatim/README.md

Ansible Role: Seriatim

Installs the Seriatim transcript processor from source. The role supports Ubuntu 26.04 on amd64 and arm64 hosts and is independently usable outside the D&D pipeline role.

The role manages its build dependencies and a root-owned source checkout, builds a native static executable, validates it, and safely installs it.

Role source and issue tracking are hosted in the ansible-role-seriatim repository and its issue tracker.

Requirements

Ansible Core 2.18 or newer is required. Install the pinned collection dependency before using or validating the role:

ansible-galaxy collection install -r collections/requirements.yml

The consuming play must set become: true or provide equivalent root privileges. The role manages system packages, classic snaps, root-owned source and state directories, and the installed executable under /usr/local by default.

Variables

Variable	Default	Description
seriatim_version	v1.5.0	Release identity expected from the installed binary.
seriatim_repository_url	https://gitea.maximumdirect.net/eric/seriatim.git	Source repository URL.
seriatim_source_ref	{{ seriatim_version }}	Git tag, branch, or commit to check out.
seriatim_build_version	{{ seriatim_version }}	Version injected into build metadata.
seriatim_source_dir	/usr/local/src/seriatim	Fully managed source checkout.
seriatim_binary_path	/usr/local/bin/seriatim	Installed executable path.
seriatim_build_state_dir	/usr/local/src/seriatim.ansible-build-state	Sidecar directory for build inputs and output state.
seriatim_manage_build_dependencies	true	Install Git and Go when enabled.
seriatim_go_snap_channel	1.26/stable	Go Snap channel.
seriatim_go_binary	/snap/bin/go	Go executable used to inspect and build.
seriatim_go_build_flags	[-trimpath]	Ordered Go build arguments before -ldflags.
seriatim_go_ldflags	-s -w -X gitea.maximumdirect.net/eric/seriatim/internal/buildinfo.Version={{ seriatim_build_version }}	Linker flags passed as one argument.
seriatim_go_package	./cmd/seriatim	Go package built from the checkout.

For development revisions, set both seriatim_source_ref and an honest seriatim_build_version. Released deployments should select immutable tags.

When seriatim_manage_build_dependencies is enabled, the role installs Git and converges the classic Go Snap to seriatim_go_snap_channel. When disabled, both Git and the configured Go executable must already be available, and Go must be version 1.25 or newer.

The checkout is authoritative: tracked changes and all untracked or ignored files beneath seriatim_source_dir are discarded during convergence. The repository URL may point to a private remote, but authentication must be provided independently through the managed host's Git configuration or SSH environment; this role does not manage credentials or accept unknown host keys.

Build and installation behavior

Builds run from the selected checkout with GOWORK=off, GOTOOLCHAIN=local, CGO_ENABLED=0, the configured ordered build flags, and the upstream version-injection linker flags. The resulting executable is staged and must report the exact configured version before it atomically replaces seriatim_binary_path. It is installed as root:root mode 0755.

The role records readable inputs, their SHA-256 fingerprint, and the installed binary checksum beneath seriatim_build_state_dir. A source commit, compiler identity, Go path, version, flags, linker flags, package, or fixed environment change triggers a rebuild. Missing or corrupt state, a modified binary, or an incorrect installed version also triggers rebuilding. Failed compilation or staged validation leaves the previous installed binary and successful state untouched.

For example, development from a branch must identify both source and output:

seriatim_source_ref: feature/example
seriatim_build_version: v1.5.0-dev

Static validation

ANSIBLE_COLLECTIONS_PATH="$PWD/.ansible/collections" \
  ../.venv/bin/ansible-playbook -i tests/inventory tests/converge.yml \
  --syntax-check
ANSIBLE_COLLECTIONS_PATH="$PWD/.ansible/collections" \
  ../.venv/bin/ansible-lint .

Development and integration validation

Create the workspace virtual environment described by the control repository and run the complete local suite from this repository with:

tests/integration

The driver installs the pinned collection into the ignored local .ansible directory, runs static checks, and then mutates the local host using privilege escalation. It manages /usr/local/src/seriatim, /usr/local/src/seriatim.ansible-build-state, and /usr/local/bin/seriatim; do not run it where those paths contain data that must be preserved. It verifies convergence, idempotence, platform guards, authoritative source cleanup, compiler-version invalidation, and preservation of a working installation after a failed build.

The driver uses temporary Go wrappers and removes them on exit. It attempts to restore the default role state after a failure. Recovery consists only of rerunning tests/integration or the default tests/converge.yml; no manual deletion of managed paths is required.

License

BSD-3-Clause