Releases

A release is a tagged build of archmax automation itself: a vX.Y.Z tag on main, a GitHub release whose notes list the pull requests merged since the previous one, and the image ghcr.io/archmax-ai/automation built from that tag. It is not an agent’s version and not a publish: those are what owners do with their own workflows, inside a running deployment.

How a release is cut is on Releasing.

Numbering

Release numbers follow semantic versioning and come from the tags alone: nothing in the repository holds a version that is bumped. The first release is v0.1.0; after that each release increments the newest vX.Y.Z tag by the part its pull request’s label asks for.

Label on the merged pull request	Increment	After v1.4.2
release	patch	v1.4.3
release:minor	minor	v1.5.0
release:major	major	v2.0.0

When a pull request carries several of these labels, the largest increment wins. A pull request merged without one is part of the next release that is cut.

What a release publishes

Artifact	Where
The tag vX.Y.Z	On the commit of main that passed the release’s CI gate
The GitHub release vX.Y.Z	The repository’s Releases page, with generated notes
The image, X.Y.Z	ghcr.io/archmax-ai/automation:X.Y.Z
The image’s minor line, X.Y	ghcr.io/archmax-ai/automation:X.Y, moved to each newer X.Y.*
The newest release	ghcr.io/archmax-ai/automation:latest

Every image is built for linux/amd64 and linux/arm64, and carries the OCI labels org.opencontainers.image.source, .version and .revision (the commit it was built from). Releases are only cut from main, so X.Y and latest only ever move forward. To pin a deployment, use the full X.Y.Z. See the image for what runs inside it.

A release can carry data updates, which rewrite the stored documents when it first starts, and its pull request says so. Pinning a deployment back to an older release afterwards makes that release refuse to start, because the database holds documents newer than it knows; the ways back are in rolling back past a data update.

The GitHub releases are the changelog: their notes are generated from the titles of the merged pull requests, so a pull request’s title is how its change is announced.

Unstable images

Every commit pushed to main whose CI passes also gets an image, ghcr.io/archmax-ai/automation:unstable-<sha>, named by the commit’s first seven characters, and ghcr.io/archmax-ai/automation:unstable moves to it. So unstable is always the newest commit on main that passed CI. An unstable image reports unstable-<sha> as its release number. It is not a release: nothing is tagged, latest stays on the newest release, and it is meant for trying main before a release is cut. Where a container can restart, pin unstable-<sha> rather than unstable. Only the newest ten unstable-<sha> images are kept; older ones are deleted.

An unstable image applies the data updates merged since the last release when it starts. Do not run it against the database of a deployment that runs a release: that release would then refuse to start, as rolling back past a data update describes.

Pull request images

Every pull request from a branch of this repository, except Dependabot’s, also gets an image, ghcr.io/archmax-ai/automation:pr-<number>, rebuilt on each push and named in a comment on the pull request. It reports pr-<number> as its release number. A pull request image is not a release: nothing is tagged, and it is meant for trying a change before it merges. It is deleted when the pull request closes.

Which release a deployment runs

The image carries its release number in APP_VERSION, and the health endpoint reports it:

curl -s https://archmax.example.com/api/health
# {"status":"ok","version":"1.5.0"}

An unstable image reports unstable-<sha>, a pull request image pr-<number>, and an image built locally with docker build ., or the platform run from source, dev. The documentation site’s header badge shows the newest release in the same way.

Pulling an image

The package starts out private, with the repository’s visibility. Until an owner of the archmax-ai organization makes it public, log in with a GitHub token that can read packages:

echo "$GITHUB_TOKEN" | docker login ghcr.io -u <github-user> --password-stdin
docker pull ghcr.io/archmax-ai/automation:1.5.0

One image serves every deployment: it holds no sign-in settings, no config and no secret. Each deployment supplies those when the container starts, as Installation describes.