From 36118f4ee4490117d07bb37181ac623df26839cd Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 23 Sep 2026 13:09:01 +1000 Subject: [PATCH] fix(release): CI owns the release stamp; :latest moves only from a release Two beads, one root: four sites stamped a version and only two of them were CI. `Taskfile.yml`'s build and `install.sh` derived GATEWAY_VERSION/RUNTIME_VERSION from `git describe`, so a from-source build claimed a release it was not running, and the stamp became a function of the commit graph -- the one input a content-checksum build cache cannot see. An empty commit moved `git describe` while `task build` reported "up to date" and shipped the previous stamp (archie-core-pdq2). Both sites now stamp `dev`: a source build says so, and the version a release carries is written into the artifact CI publishes. That removes the non-file input rather than caching it, and traceability for a local build is the checkout it came from. `deploy.yml` published `:latest` from any push to main, so a release's own stamping survived only until the next ordinary commit -- minutes, in an active repo -- and a host deploying :latest reported dev, leaving the update path unable to tell current from stale (archie-core-i5nb). `:latest` now moves only from a commit that IS a release; every other build publishes `:edge` (mutable, newest main) and `sha-` (immutable). A host that runs releases follows `:latest`; a host that tracks main follows `:edge`, which RELEASING.md now says. Verified: `task build` reports `archied dev`; the new workflow test fails against the old workflow on all five guards and passes after; deploy.yml parses; install.sh passes `bash -n`. Gated with `task check` (exit 0) at 6046aaf4 -- the v1.39.0 base, CI-green -- with these five files applied. It is NOT gated at HEAD: HEAD carries an unrelated red, `TestTaskProtoCarriesEveryDomainField`, because fe2a8e6d added ParkClass and RemediationRounds without the proto mapping. This change neither causes nor fixes that. --- .github/workflows/deploy.yml | 39 ++++++++++++++++++++++++++---------- RELEASING.md | 5 +++++ Taskfile.yml | 23 ++++++++++++--------- deploy_workflow_test.go | 31 ++++++++++++++++++++++++++++ install.sh | 12 +++++++++-- 5 files changed, 87 insertions(+), 23 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 7c9208bbf..b01f85fef 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -12,7 +12,7 @@ on: # preceding fix, say) previously queued a full gate+build for each one, # several minutes apiece, with no caching -- so a burst of pushes left # three deploys racing in parallel for the same runner capacity. Only the -# last one's images matter (both jobs push :latest), so cancel a +# last one's images matter (each job pushes its image tags), so cancel a # superseded run rather than let it fight for resources it can't use. # # Keyed on the commit, not github.ref: `git push --follow-tags` pushes @@ -140,7 +140,7 @@ jobs: exit 1 fi if ! git tag --points-at HEAD | grep -qE '^(v[0-9]|archied/v|archie/v)' ; then - echo "::warning ::No release tags at HEAD, so this build publishes :latest for a commit that is not a release. It is stamped dev+ and tagged sha- so it stays traceable and restorable, but it supersedes the previous release's :latest stamping until the next release is cut." + echo "This commit is not a release, so the images are published as :edge and sha-; :latest keeps naming the newest release." fi build-and-push: @@ -184,12 +184,13 @@ jobs: RUNTIME_VERSION="${RUNTIME_TAG#archie/}" [ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION="${RELEASE_TAG#v}" [ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="${RELEASE_TAG#v}" - # Not a bare `dev`. A literal dev tells an operator nothing about which - # build they are running, and it is what made a release's stamping look - # transient: the next commit to main republished :latest as `dev`. The - # commit is appended so a main build is identifiable and is visibly not - # a release. (On an untagged push GITHUB_SHA IS the commit — the tag - # case is handled by the dereference above.) + # `dev+` is what a build that is NOT a release reports, and it is + # honest now that such a build no longer publishes :latest: the version + # names the commit it came from, and the sha- tag makes it + # restorable. Before, this same string reached :latest minutes after a + # release and made the release's own stamping read as dev + # (archie-core-i5nb). (On an untagged push GITHUB_SHA IS the commit — + # the tag case is handled by the dereference above.) [ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION="dev+${GITHUB_SHA:0:12}" [ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="dev+${GITHUB_SHA:0:12}" # Keep the raw tag presence separate from the version fallback: a @@ -202,6 +203,24 @@ jobs: echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT" echo "gateway=$GATEWAY_VERSION" >> "$GITHUB_OUTPUT" echo "runtime=$RUNTIME_VERSION" >> "$GITHUB_OUTPUT" + # :latest names the newest RELEASE, so only a commit that IS one + # publishes it. A push to main publishes :edge (mutable, newest main) + # and sha- (immutable) instead. That is what stops a release's + # :latest stamping from being overwritten minutes later by the next + # ordinary commit, which left a host reporting dev and made the update + # path unable to tell current from stale (archie-core-i5nb). + # + # `if` blocks rather than `[ -n "$X" ] && echo`: the latter returns + # non-zero when the test fails, and these steps run under `set -e`. + { + echo "archied_tags<> "$GITHUB_OUTPUT" - name: Build and push archied uses: docker/build-push-action@v6 @@ -209,9 +228,7 @@ jobs: context: . file: Dockerfile.archied push: true - tags: | - ghcr.io/samcharles93/archied:latest - ghcr.io/samcharles93/archied:sha-${{ steps.commit.outputs.sha }} + tags: ${{ steps.versions.outputs.archied_tags }} build-args: | GATEWAY_VERSION=${{ steps.versions.outputs.gateway }} RUNTIME_VERSION=${{ steps.versions.outputs.runtime }} diff --git a/RELEASING.md b/RELEASING.md index 64d391865..af5650d3d 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -76,6 +76,11 @@ Tagging one version produces, from a single `deploy` run: `ghcr.io/samcharles93/archie-agent:latest`. The runtime image is rebuilt by the release, so runtime commits merged to `main` do not reach a running sandbox until the host pulls the new image. +- **`:latest` names the newest release, not the newest commit.** A push to `main` + that is not a release publishes `archied:edge` (mutable, tracking `main`) and + `archied:sha-` (immutable) instead, so a release's `:latest` stamping is + not overwritten minutes later by the next ordinary commit. A host that runs + releases follows `:latest`; a host that tracks `main` follows `:edge`. - **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-messaging`, `archie-playbooks`) for linux/amd64, packs them with diff --git a/Taskfile.yml b/Taskfile.yml index 185dd0381..f091f22f3 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -439,17 +439,20 @@ tasks: build: desc: Build archie services and agent binaries - # Version stamping used to live only in Dockerfile.archied, so any build - # from source -- including a host deployment -- reported "dev" for - # both components and /version was useless there. Derive the same - # -X values from the release tags so a source build is stamped too. - # git describe (without --abbrev=0) yields 1.7.0-2-gbb54786 when HEAD is - # past the tag, which is the honest answer for a mid-cycle build. + # A from-source build is not a release, and CI is the only thing that stamps + # one: the version a release carries is written into the artifact CI + # publishes, the zip's binaries and the container image, and is never + # derived from whatever tags a local checkout happens to have. + # + # Deriving it here also made the stamp a function of the commit graph, which + # is the one input a content-checksum build cache cannot see: an empty + # commit moved `git describe` while `task build` still reported "up to date" + # and shipped the previous stamp (archie-core-pdq2). Stamping `dev` removes + # the non-file input rather than caching it, and a local build's + # traceability is the checkout it came from. vars: - GATEWAY_VERSION: - sh: git describe --tags --match 'archied/v*' 2>/dev/null | sed 's|^archied/v||' || echo dev - RUNTIME_VERSION: - sh: git describe --tags --match 'archie/v*' 2>/dev/null | sed 's|^archie/v||' || echo dev + GATEWAY_VERSION: dev + RUNTIME_VERSION: dev sources: - "**/*.go" - go.mod diff --git a/deploy_workflow_test.go b/deploy_workflow_test.go index c215212a8..8e17fa3ab 100644 --- a/deploy_workflow_test.go +++ b/deploy_workflow_test.go @@ -50,6 +50,37 @@ func TestDeployWorkflowOnlyPublishesRuntimeImageForTaggedRelease(t *testing.T) { } } +// TestDeployWorkflowPublishesLatestOnlyFromARelease pins the rule that keeps a +// release's :latest stamping from being overwritten by the next ordinary commit. +// +// build-and-push runs on any push to main and used to always push :latest, so a +// release's own stamping survived only until the next commit — minutes, in an +// active repo — and a host deploying :latest reported dev, leaving the update +// path unable to tell current from stale (archie-core-i5nb). :latest now moves +// only from a commit that IS a release; everything else publishes :edge and an +// immutable sha-. +func TestDeployWorkflowPublishesLatestOnlyFromARelease(t *testing.T) { + source := readDeploymentFile(t, ".github/workflows/deploy.yml") + + for _, required := range []string{ + `if [ -n "$RELEASE_TAG" ]; then`, + `echo "ghcr.io/samcharles93/archied:latest"`, + `echo "ghcr.io/samcharles93/archied:edge"`, + `archied_tags< Building native archie binaries..." # refuses to self-update (internal/releaseupdate.ErrUnknownInstallType) # rather than guess whether /update's configured install command is # even the right kind of update for a script-built native binary. - GATEWAY_VERSION="$(git describe --tags --match 'archied/v*' 2>/dev/null | sed 's|^archied/v||' || echo dev)" - RUNTIME_VERSION="$(git describe --tags --match 'archie/v*' 2>/dev/null | sed 's|^archie/v||' || echo dev)" + # A from-source build is not a release, and CI is the only thing that stamps + # one: the version a release carries is written into the artifact CI + # publishes -- the zip's binaries and the container image -- and is never + # derived from whatever tags a local checkout happens to have. Deriving it + # here made a source-built host claim a release it was not running, and made + # the stamp a function of the commit graph, which is the one input a + # content-checksum build cache cannot see (archie-core-pdq2). A source build + # says `dev`; its traceability is the checkout it came from. + GATEWAY_VERSION="dev" + RUNTIME_VERSION="dev" LDFLAGS="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${GATEWAY_VERSION}" LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=${RUNTIME_VERSION}" LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary"