From d645af03a55fd2fc04218510ed26d02472f0af2c Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 17 Sep 2026 07:20:33 +0000 Subject: [PATCH] docs(release): document what a release publishes The zip and its Release were undocumented: RELEASING.md described the images and the gate, and nothing about dist-zip, the Release asset, or that a gateway-only release does not rebuild the agent image. Adds that, plus the consequence that bit this release -- Actions runs the workflow from the tagged commit, so a deploy.yml fix must be an ancestor of the tag rather than a commit on top of it. --- RELEASING.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/RELEASING.md b/RELEASING.md index 72adc62d6..91f9f8e5e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -63,9 +63,37 @@ Pushing is a separate, explicit step — never push without confirming first The deploy workflow reads tags pointing at `HEAD`; pushing the commit without its tags gets images stamped `dev`. +## What a release publishes + +Tagging both components at one commit produces, from a single `deploy` run: + +- **Container images** — `ghcr.io/samcharles93/archied:latest` and, when the + runtime moved, `ghcr.io/samcharles93/archie-agent:latest`. A gateway-only + release (`RUNTIME=skip`) does not rebuild the agent image, so runtime commits + merged to `main` do not reach a running sandbox until an agent release is cut + and the host pulls the new image. +- **A GitHub Release with a distribution zip** — `dist-zip` builds every + process the reference deployment runs (`archied`, `archie-gateway`, + `archie-state-store`, `archie-ui`, `archie-playbooks`) for linux/amd64, packs + them with `deployments/INSTRUCTIONS.md` and the changelogs, and attaches the + zip to the Release for the **archied** tag. The Release body is that + version's `CHANGELOG.archied.md` section. Both jobs are keyed to the archied + tag, so a gateway-only release still produces the zip. + +The zip is also uploaded as an Actions artifact, but that is a backup copy: +artifacts expire after 90 days and need an Actions login to download. The +Release asset is the durable, operator-reachable one. + ## Gate CI (`deploy.yml`) runs `task check` before building images, then verifies any release tag at `HEAD` has a matching `[version]` section in its changelog. A tag with no changelog entry is a hard failure. No tags at `HEAD` is a warning, not a failure — images get stamped `dev`. + +One consequence worth knowing when a release commit needs amending: GitHub +Actions runs the workflow **from the commit that triggered it**, so a fix to +`deploy.yml` only takes effect for a release if it is an ancestor of the tagged +commit. Delete and re-cut the tags (`git tag -d`, `task release`) rather than +committing the fix on top of an already-tagged release. +