Mecatl Release Cutting

Cut a mecatl release

A release is a vX.Y.Z git tag. Pushing that tag triggers .github/workflows/release.yml, which publishes signed images (mecated, mecatui, mecak8s, execution provider/workload, Studio, and the Slack-bot example), Helm charts, and versioned microVM and Brood Box artifacts. It also publishes a GitHub Release carrying darwin/linux x amd64/arm64 CLI archives, a checksums.txt, cosign bundles, SBOMs, and build provenance, and pushes a mecatl formula bump to the public stacklok/homebrew-tap repository. There is no version baked into the Go code — the tag IS the release.

Two consequences of the Homebrew half, before you start:

• A published tag is immutable in practice. The formula records the release archives' SHA256 checksums for a specific tag. Deleting and re-pushing a vX.Y.Z that already produced a release and a tap commit leaves the tap pointing at checksums that no longer match, which breaks brew install for everyone. If a release goes wrong after the tap commit lands, fix forward with the next patch version. Re-tagging is only an option when the run failed before publishing anything.
• Validate release-only inputs BEFORE tagging, not by pushing a throwaway tag. The release-PR workflow checks execution-image digest pins before it opens the PR; CI checks the Brood Box build and microVM defaults handoff. A local task release:snapshot && task release:verify only checks CLI archives and Homebrew packaging; it does not prove the container publishing jobs work.

Nothing pushes a commit to main. The release runs through an ordinary pull request: you dispatch a workflow, a bot opens the PR, a human merges it, and a bot tags the merge commit. You never run git push origin main, and you never create the tag by hand.

VERSION (repo root, bare semver — 0.0.34, not v0.0.34) is the source of truth for the release version. The release PR propagates it to the mecak8s chart version, appVersion, and default image tag. The workflows verify those values directly rather than maintaining a fixed list of files that a release PR may change.

It did not used to be. mecatequi-reusable.yml referenced its three sibling composite actions by a hardcoded @vX.Y.Z literal, so every release had to bump those pins in the same tagged commit or ship version skew. That self-reference — a file naming a tag that does not exist yet — is why a release needed a commit on main at all. The pins are now $/ self-repository refs, which resolve to this repo at the exact ref the workflow is running from, so there is nothing left to bump and skew is impossible rather than merely policed.

Steps

Run from the repo root.

1. Confirm what you're shipping. The release tags whatever is on main when the release PR merges. Review what has landed since the last tag:

   git tag --sort=-v:refname --list 'v*' | head -1   # e.g. v0.0.33
   git log <last-tag>..origin/main --oneline

   Confirm the bump type with the operator before dispatch; patch is the established release cadence even when the range includes additive changes. Do not infer a minor bump from commit subjects alone.

2. Dispatch the release-PR workflow. This is the only step that starts a release:

   gh workflow run create-release-pr.yml -f bump_type=patch
   gh run watch "$(gh run list --workflow=create-release-pr.yml --limit 1 --json databaseId --jq '.[0].databaseId')"

   The workflow validates the tracked ARG defaults in build/execution-provider/Dockerfile and build/execution-workload/Dockerfile on main: the Go builder, static provider runtime, and Brood Box workload runtime must have tagged digest pins available for Linux amd64 and arm64; it also builds both images without publishing. The tag workflow repeats the pin and availability validation on the merged commit before tagging. Renovate updates the pins through its native Dockerfile manager; no image repository variables are required. If validation fails, fix the tracked pins through review (or retry a transient registry failure); do not bypass the check. The publishing job validates the tagged checkout again. The workflow bumps VERSION, the mecak8s chart version and app version, and the chart's default image tag. It opens Release vX.Y.Z from branch release/vX.Y.Z, then asserts that the required values are synchronized. If that verification step fails, do not merge the PR; close it, delete the branch, and read the job log.

3. Review the release PR like any other PR and confirm that all changes belong to the release update:

   gh pr list --head "release/vX.Y.Z" --json number,url,files
   gh pr diff <number>

   Wait for CI to go green. The PR is opened by the release GitHub App, so it triggers checks normally.

4. Squash-merge it. A human does this — it is the approval gate, and it is the only way VERSION changes on main:

   gh pr merge <number> --squash

   The tagging workflow does not read the commit subject — it asks GitHub which PR produced the commit and requires a merged, bot-opened PR from branch release/vX.Y.Z with matching version values. The squash title and the number of updated files do not affect the tag gate.

5. Watch the tag get created. Merging fires create-release-tag.yml, which re-verifies the commit and pushes the annotated tag. That push fires release.yml on its own — the tag is pushed by a GitHub App installation token precisely so the cascade happens, where a GITHUB_TOKEN-pushed tag would trigger nothing:

   gh run watch "$(gh run list --workflow=create-release-tag.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
   git fetch --tags && git tag --sort=-v:refname --list 'v*' | head -1

6. Confirm the release run started, then wait for every publishing job. A successful CLI archive or one green image is not a complete release. In particular, check the mecated, execution provider/workload, Brood Box resolution, microVM, chart, and CLI/Homebrew jobs before reporting success:

   gh run list --workflow=release.yml --limit 3
   gh run watch "$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')"

7. Verify the GitHub Release carries every artifact. It must not be a draft, and it must have four archives plus a checksum file, with a cosign bundle and an SBOM alongside each. Also require brood-base-index.json, brood-platforms.json, and the microvm-default-*.json completion assets for each platform. Missing assets mean the release is incomplete even if the CLI archives are available:

   gh release view vX.Y.Z --json isDraft,assets --jq '{draft: .isDraft, assets: [.assets[].name]}'

   Then prove one archive is actually usable rather than trusting the asset list. Use the repo-local .scratch/ dir, never /tmp (AGENTS.md):

   mkdir -p .scratch/release-vX.Y.Z
   gh release download vX.Y.Z -p 'checksums.txt' -p '*darwin_arm64*' -D .scratch/release-vX.Y.Z
   (cd .scratch/release-vX.Y.Z \
     && shasum -a 256 -c checksums.txt --ignore-missing \
     && tar -xzf mecatl_*_darwin_arm64.tar.gz \
     && ./mecatui --version && ./mecated --version)

   Both --version lines must print the tag you just cut. A dev+<revision> output means the release build lost its BUILD_ID linker stamp — a release bug, not a cosmetic one, because the public install docs claim a released binary reports its tag.

   If the run died between "release created" and "assets uploaded" it leaves a DRAFT, which a lookup by tag does not return, so a naive re-run fails trying to create the release again. Recover with gh release delete vX.Y.Z --cleanup-tag=false --yes, then re-dispatch.

8. Verify the Homebrew tap got the formula bump:

   gh api repos/stacklok/homebrew-tap/commits --jq '.[0].commit.message'
   gh api repos/stacklok/homebrew-tap/contents/Formula/mecatl.rb --jq '.content' \
     | base64 -d | grep -E 'version|url|sha256' | head

   The top commit must name the version you just cut, and the formula's url and sha256 values must match the release assets from step 7.

   While stacklok/mecatl is private, brew install stacklok/tap/mecatl fails even after a correct tap commit: Homebrew's downloader does not authenticate, so it cannot fetch a release archive from a private repository. The tap commit landing is the whole verification until the repository goes public; this is known and accepted. Once it is public, run the real end-to-end check once:

   brew update && brew install stacklok/tap/mecatl && mecatui --version

The engine module is tagged separately

The vX.Y.Z release above is the root repo / mecated image release. The importable core, github.com/stacklok/mecatl/engine, is its own Go module (ADR 0036) with its own tag grammar engine/vX.Y.Z (distinct from the root tags). It carries a public-API compatibility contract (engine/COMPATIBILITY.md, ADR 0037).

• The first engine/vX.Y.Z tag is engine/v0.0.1 — a deliberate "earliest, no stability promise" initial cut (the lowest pre-v1 patch, signalling zero stability commitment for the very first published surface). Cutting it is a deliberate maintainer decision (deferred per ADR 0037) — do NOT cut it as part of a routine root release unless asked. The grammar is engine/vX.Y.Z, distinct from the root vX.Y.Z tags; the two version lines are independent. SUBSEQUENT bumps follow engine/COMPATIBILITY.md (pre-v1: minor = additive, patch = fixes).