[jgoux]

Summary

Each build now gets its own immutable release version, <upstream>-r<N>, instead of reusing the upstream version string and overwriting it with force=true. A packaging fix becomes a new revision; published bytes are never replaced. This lets the CLI pin every artifact by content.

• Release version. R = <upstream>-r<N>, where N starts at 0. R names:

  • the GitHub release and git tag;
  • the archive, manifest and SBOM assets;
  • the GHCR tags (:R, :R-linux-*, :R-native-*), ECR Public and S3 paths;
  • the OCI image.version label and the local image tag.

  Everything that talks to upstream still uses the upstream version: source checkout, upstream image lookups, external snapshots, and version strings baked into binaries.

• Commit point.

  • The GitHub release is created last and create-only. A revision is taken once its release exists.
  • scripts/plan-release-revision.sh allocates N from the full paginated release list before anything is pushed.
  • Publishing is only allowed from main. PR branches use validation_only.

• Workflow inputs. force is removed. hotfix and hotfix_reason publish the next revision of an already-published upstream version, and the reason goes into the release notes.

• Integrity.

  • The per-platform SHA256SUMS now also covers the final manifest.json.
  • Manifests record version (R), upstream_version and revision.

• CLI notification. After the release is created, the workflow sends slim-release-published ({service, upstream_version, revision, release_version}) to the CLI repo, so hotfixes can be picked up. The step fails loudly if it can't dispatch.

• Mirrors and results. The ECR/S3 audit and backfill, and the README results tables, only consider -rN releases, ordered by upstream version and then revision. Mirrors are reconciled against the committed GHCR digests.

• Legacy releases. Releases without -rN are frozen and ignored. Nothing rewrites or deletes them, so already-released CLIs keep working.

• Poller. A version counts as published only when an -rN release exists, and force is no longer passed.

• Release floors (release-policy decision). Each polled service's release_floor moves to its third-newest stable tag. The per-service values are in the feat(poll) commit body.

  • This stops the poller from rebuilding the whole legacy backlog.
  • New rule in AGENTS.md: a floor must never be above a version the CLI catalog pins.
  • Studio's floor is 2026.09.14-sha-4dd8a95, the last buildable tag; services/studio/REPORT.md records newer tags as unreleasable.

• Docs. Updated README.md, AGENTS.md, docs/design/ecr-mirror-dispatch.md, HOST_NATIVE_ARTIFACTS.md, IMAGE_CONTRACT.md and the Nix playbook.

The matching CLI change (pinned digests for image, archive and manifest, plus hotfix pickup) is in draft PR supabase/cli#6883. Its pins get filled in once the -r0 republish has run.

After merge

1. Publish auth r0, then a hotfix=true r1, and check that r0's release assets, GHCR digests and S3 objects are unchanged.
2. The poller republishes the last 3 versions of each polled service as -r0. Dispatch mailpit and vector by hand.

Test plan

• Host-only contract tests from repository-checks.yml, bun test for ecr-mirror and publish-native-oci, bash -n (including macOS bash 3.2), and shellcheck
• POLL_DRY_RUN=1 against this repo: it would dispatch only versions at or above the new floors, with no force
• repository-checks green on this PR
• service-release.yml validation_only=true on this ref for auth (derived image), vector (mirrored image), studio (Docker Hub) and postgres 17: archive names end in -r0-<target>, manifests carry the new fields, and SHA256SUMS lists the manifests (auth, vector, studio, postgres). I downloaded the auth darwin-arm64 assets and checked them: the names end in -r0, the manifest has version: v2.197.0-r0, upstream_version: v2.197.0 and revision: 0, and shasum -c passes on all three files in SHA256SUMS.

[avallete]

The overall design is solid. The planner is exactly anchored and paginated, runs are serialised per service and version, the release is created only if it doesn't already exist, publishing is limited to main, and old-style releases can't be mistaken for revisions. The host tests pass locally.

One path still breaks "published bytes are never replaced", though: re-running an old failed run can move the tags of a revision that another run has since published. Details are inline. Summary:

1. Significant: re-running an old failed run can overwrite the GHCR, ECR and S3 tags of an already-published revision. Fix: add a release-exists guard at the start of each pushing job.
2. Significant: draft releases count as taken revisions in the planner and the poller.
3. DX: the slim-release-published dispatch can't be retried once the release exists.
4. Minor regression: the ECR mirror's "latest" ordering sorts same-date Studio tags by the digits in their commit hash.
5. DX: a few new workflow tests assert source text rather than behaviour, and there are some comments to tidy up.

Minor, non-blocking: $SERVICE-$VERSION.external-release.json and .oci-provenance.json are still named with the upstream version. They can't collide, since each release has its own assets. Rename them to the release version only if it's meant to cover every asset name.

[jgoux]

Thanks for the thorough review, @avallete. All five points are addressed in 5d0edad; each thread has the details.

1. Re-run overwrite. Every pushing job (publish-image, publish-natives, mirror-ecr) now starts with a guard that fails when the revision is already published.
2. Drafts. Draft releases no longer count as taken in the planner or the poller. The create step deletes a stale draft of the same revision before creating it.
3. Notification. The CLI dispatch is now its own retryable notify-cli job. A missing CLI_MIRROR_DISPATCH_TOKEN fails plan before anything is built.
4. Studio ordering. Releases compare by upstream version (SHA suffix stripped), then by revision within the same upstream, then by publishedAt. This applies in ecr-mirror.ts and download-latest-release-manifests.sh.
5. Tests and comments. The source-text assertions are replaced with tests that run the real run: blocks against a fake gh, and the comments are tidied.

On the non-blocking note, I've left $SERVICE-$VERSION.external-release.json and .oci-provenance.json named with the upstream version. They record the upstream snapshot rather than our packaging, and each one ships inside its own <svc>-<U>-r<N> release, so they can't collide.

[avallete]

Thanks for the quick turnaround. I re-checked 5d0edad, and all five points from the first round are addressed:

• The guards come before every push.
• Draft handling is safe, because runs of the same version take turns in the concurrency group.
• notify-cli can be retried on its own.
• The TypeScript and Python comparators agree on every tricky version list I tried.
• The tests now run the real step scripts.

The host tests and actionlint pass locally.

Two things still need a change before this is safe:

1. notify-cli is skipped whenever mirror-ecr fails. The skip comes from the implicit success() in its if:. Adding !cancelled() fixes it (details inline).
2. The new guard fails open on some API errors. gh release view can report "release not found" when the published-release lookup itself errored (details inline).

Non-blocking:

• The draft-filter test in the poller suite can't fail (inline).
• The token check is duplicated (inline).
• A few comments still describe history, or repeat another comment, rather than giving a reason:
  • the "were dropped" / "Kept as the one structural check" comments in test-external-workflows.sh;
  • the long comparator comment in ecr-mirror.ts, which repeats the Python one;
  • the long comment in the notify step.
• For Studio tags from the same date, "latest" now means most recently published. So a hotfix -r5 of an older sha outranks a newer sha's -r0. That's probably intended, but worth a sentence in docs/design/ecr-mirror-dispatch.md.

[jgoux]

Thanks @avallete. All four round-2 comments are addressed in 76120b5, with details in each thread:

• notify-cli now uses !cancelled().
• Release lookups go through the REST endpoint and fail closed.
• The test stubs run the real --jq.
• The token check is done once, and the unreachable paths are removed.

After that I ran an independent review of the whole branch, going back and forth until we agreed. It raised two small issues, both fixed in ea4e189:

• hotfix_reason must now contain a non-whitespace character. It previously accepted a reason made only of tabs or newlines.
• The "Stage release assets" test now checks the manifest digest against an independently computed sha256, and checks that the checksum file stays sorted.

The follow-up review pass found nothing else actionable. CI is green.

[avallete]

Approving. Thanks for working through all the rounds. I re-checked 76120b5 and ea4e189, and all four round-2 points are fixed:

• notify-cli now has !cancelled(). No other job has the same implicit-success() problem.

• The release check now queries the tag directly and fails closed. I checked this against real GitHub with gh 2.97.0:

  • a missing tag gets a 404, and the check lets the push continue;
  • a published tag gets a 200, and the check stops with the immutability message;
  • a 401 or any other error stops the run.

  Stale drafts are found by listing releases and deleted by id, which is the right split.

• The --jq-honoring stubs now catch a regression: removing select(.draft | not) from the planner or the poller makes their suites fail.

• The token check is a single step in plan, and validation-only runs still work without the token.

• A whitespace-only hotfix_reason is rejected before any work starts.

The host tests and actionlint pass locally.

A few optional nits are inline. One more, not worth a thread: the check can't tell a missing tag from a repo that doesn't exist or can't be accessed (gh returns identical output for both). That's not reachable while GH_REPO is always set to github.repository, so it's just for awareness.

[jgoux]

Thanks for the approval, @avallete. All four inline nits are addressed in 10caef8.

I also cleaned up three small leftovers:

• plan-release-revision.sh now rejects an empty service, upstream version or ref with exit 2.
• An explicit ecr-mirror sync SERVICE:<legacy tag> now says the version isn't a revision release, instead of "no published releases found".
• The SOURCE_REF comment in lib.sh is corrected.

On the missing-repo versus missing-tag note: agreed. The check can't tell them apart, but that can't happen while GH_REPO comes from github.repository, so I've left it as is.