Adopt Commit-Based Container Tags

Replace the current git-tag-triggered container build system with path-based triggers and commit-SHA-based image tags, so that container versions reflect the actual bundled app version and are traceable to exact source commits.

Context

Currently, container builds trigger on git tags matching <container>-vX.Y.Z. The version is chosen arbitrarily at release time and is not connected to the upstream app version bundled in the image. This creates several problems:

• Version opacity — v1.0.0 of a container tells you nothing about which upstream version it bundles
• Manual release step — mise run container-tag-and-release must be run by hand for every build
• No automatic rebuilds — changes to a container’s build files don’t trigger builds unless someone creates a tag
• Mutable risk — version tags can be re-pushed (addressed separately by enforce-tag-immutability, but commit SHAs are inherently unique)

New Scheme

Triggers

All container builds are triggered manually via mise run container-build-and-release <name> (which dispatches the workflow). Accepts two inputs:

• container (required) — which container to build
• ref (optional, string) — the source commit SHA to build, defaulting to GITHUB_SHA

The workflow classifies the container by build type and routes to the correct runner.

Version Source

Each container’s version is extracted at build time from existing declarations — no separate VERSION file:

• Dockerfile builds: parsed from ARG CONTAINER_APP_VERSION=<value> in the Dockerfile
• Nix builds: extracted from version = "..." in default.nix, or CONTAINER_APP_VERSION from the Dockerfile, or dagger call nix-version for nixpkgs packages

The add-container-version-sync-check prek check ensures these declarations stay in sync with service-versions.yaml. See pin-container-versions for the work to ensure every container has a parseable version.

Image Tag Format

Build type	Tag format	Example
Dockerfile	vX.Y.Z-<sha>	v2.2.17-abc1234
Nix	vX.Y.Z-<sha>-nix	v2.17.0-abc1234-nix

Where:

• X.Y.Z is the version of the most relevant bundled app (e.g., miniflux 2.2.17, navidrome 0.60.3)
• <sha> is the 7-char short commit SHA of the source tree used for the build

What This Replaces

• The container-tag-and-release mise task is replaced by container-build-and-release — it triggers a manual workflow dispatch instead of creating git tags
• Git tags of the form <container>-vX.Y.Z are no longer used to trigger builds
• The container-list mise task displays the new tag format

Key Files

File	Change
.forgejo/workflows/build-container.yaml	Replace tag trigger with path + dispatch triggers; compute version and SHA
.forgejo/workflows/build-container-nix.yaml	Same trigger changes; add -nix suffix to new tag format
src/blumeops/main.py	Accept SHA parameter; publish with new tag format
mise-tasks/container-build-and-release	New task replacing container-tag-and-release; triggers workflow dispatch
mise-tasks/container-list	Updated tag display for new format
docs/how-to/deployment/build-container-image.md	Updated documentation

Interaction With Other Prereqs

• enforce-tag-immutability — Commit SHA tags are inherently unique, reducing the scope of immutability enforcement
• wire-ci-registry-auth — Auth changes apply regardless of tagging scheme; no conflict

Related

• harden-zot-registry — Parent goal
• enforce-tag-immutability — Complementary prereq (scope may narrow)
• build-container-image — How-to doc to update