Skip to content

feat(ENG-15913): add a release channel for each major version - #627

Merged
cloudsmith-iduffy merged 8 commits into
masterfrom
eng-15913
Nov 19, 2026
Merged

cloudsmith-iduffy merged 8 commits into
masterfrom
eng-15913

Conversation

@cloudsmith-iduffy

@cloudsmith-iduffy cloudsmith-iduffy commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Release channels let users stay on one major version of the CLI. A release channel is a name that points at the highest release in a group. For example, the Docker Hub tag 1 points at the highest 1.x release.

This PR adds a channel for each major version, and stops an older release from moving a channel back. #629 builds on this PR to keep cloudsmith update in the running major version.

Release 1.40.2 when 1.40.1 is the highest release

  1. publish-binaries pushes each install manifest under two names: cloudsmith-cli-manifest-<target>, as today, and the new cloudsmith-cli-v1-manifest-<target>. Cloudsmith resolves versions/latest of each name by semantic version, so the v1 name always gives the highest 1.x release.
  2. publish-containers pushes only cloudsmith/cloudsmith-cli:1.40.2. Today it also moves latest, 1, and 1.40.
  3. publish-github publishes the v1.40.2 release, but doesn't mark it as the GitHub Latest release.
  4. promote-channels finds that 1.40.2 is the highest release overall, in 1.x, and in 1.40.x. It marks v1.40.2 as Latest, and points the Docker Hub tags latest, 1, and 1.40 at 1.40.2.
  5. notify-downstream-repos sends the release event to the Homebrew tap, the GitHub Action, and three new repositories: cloudsmith-ado-integration, orb, and cloudsmith-sbx-kits. Each repository opens a pull request that bumps its CLI version to 1.40.2.

Release 2.0.0, then 1.40.3

  • 2.0.0: promote-channels marks v2.0.0 as Latest, and points latest, 2, and 2.0 at 2.0.0. The first cloudsmith-cli-v2-manifest-<target> manifests appear.
  • 1.40.3: promote-channels points 1 and 1.40 at 1.40.3. latest and Latest stay on 2.0.0. Without this PR, 1.40.3 moves latest back to 1.40.3.

Re-run an old release

After 1.40.3 ships, re-run the v1.40.2 release. promote-channels moves nothing, because 1.40.3 holds 1 and 1.40. Without this PR, the re-run moves every channel back to 1.40.2.

The same check covers a failed release. If 1.40.3 fails, 2.0.0 ships, and then you re-run 1.40.3, latest stays on 2.0.0. promote-channels reads the published releases when it runs, not when the release starts.

Release 2.0.0 and 1.40.3 at the same time

promote-channels runs for one release at a time, because all release tags share one concurrency group. Each run reads the published releases just before it moves a channel.

Without the group, 1.40.3 can read the releases before 2.0.0 is published, decide that it holds latest, and then push after 2.0.0. The queue: max setting keeps a waiting run. Without it, a new pending run cancels the waiting one.

Other changes

  • .github/scripts/promote_channels.py decides which channels to move, and moves them. Its header has the same examples. It runs with uv run. Its only dependency, requests, is declared in the script header.
  • A tag that isn't MAJOR.MINOR.PATCH fails promote-channels.
  • .github/scripts is exempt from the ruff rule that bans a module-level import requests. The rule keeps CLI startup fast, and the CI scripts aren't part of the CLI.
  • The Docker Hub repository name comes from vars.DOCKERHUB_REPOSITORY. The default is cloudsmith/cloudsmith-cli. A scratch repository can set its own name to test the release flow.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Refactoring
  • Other (please describe)

Additional Notes

ENG-15913.

Testing

  • Against the real cloudsmith-cli releases, the channel check gives the same result as the earlier shell version for 9 versions.
  • Against a fake API with three pages, a draft, and a tag that isn't a release, the channel check gives the same result for 7 versions.
  • Against a fake API and a fake docker:
    • With v1.40.1 and v2.0.0 published, v2.0.0 becomes Latest and moves latest, 2, and 2.0.
    • v1.40.2 then moves only 1 and 1.40.
    • A re-run of v1.40.1 moves nothing.

Still to do before this PR leaves draft

  • Run publish-github and promote-channels in a private scratch repository, with the same script and concurrency settings. Push v1.40.0, v2.0.0, v1.40.1, and v1.40.2 close together. Check that every waiting run completes, that Latest ends on v2.0.0, and that v1.40.2 moves 1 and 1.40 but not latest. Add the run links here.
  • Run the full release flow in a scratch repository with the tags 1.40.0, 2.0.0, and 1.40.1. Check the manifests and the pinned Docker Hub tags. PyPI trusted publishing is bound to this repository, so publish-github and promote-channels don't run there. The test above covers them.

🤖 Generated with Claude Code

Each release also pushes its install manifest as
cloudsmith-cli-v<MAJOR>-manifest-<target>. The update check and
`cloudsmith update` stay in the running major version, and suggest a
higher major version without installing it. The upgrade commands for
pip, pipx, uv and Docker stay in the running major version.

The Docker Hub floating tags and the GitHub "Latest" release move only
for the highest release in their channel. A pre-release moves no
channel and sends no downstream event. The downstream event now also
goes to cloudsmith-ado-integration, orb and cloudsmith-sbx-kits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 18, 2026 11:51

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Release tags can publish concurrently using stale channel eligibility flags, allowing an older image to overwrite newer floating Docker tags.

1 open issue
What changed in this PR

Adds per-major release channels so CLI updates stay within the installed major version while notifying users about newer majors and their release notes.

Changes:

  • Publishes per-major manifests and gates floating release channels and downstream notifications.
  • Adds major-specific update state, newer-major notices, and constrained package-manager upgrade commands.
  • Extends tests and documents the new update behavior.
File Description
cloudsmith_cli/​core/​update_check.py Resolves major-specific manifests, caches state per major, and shows upgrade notices.
cloudsmith_cli/​core/​tests/​test_update_check.py Tests channel selection, state isolation, and newer-major notices.
cloudsmith_cli/​core/​tests/​test_installation.py Checks major-constrained upgrade instructions.
cloudsmith_cli/​core/​installation.py Constrains pip, pipx, uv, and Docker upgrade commands.
cloudsmith_cli/​cli/​tests/​commands/​test_update.py Tests newer-major reporting and updated manifest handling.
cloudsmith_cli/​cli/​tests/​commands/​test_main.py Updates notice and upgrade-command expectations.
cloudsmith_cli/​cli/​commands/​update.py Uses major-aware manifests and reports newer majors in text and JSON.
CHANGELOG.md Documents release channels and update behavior.
.github/​workflows/​release.yml Publishes major manifests, gates channel promotion, and expands downstream notifications.
.github/​scripts/​release-channels.sh Determines release eligibility for each floating channel.

Review effort: Balanced

Comment thread .github/workflows/release.yml Resolved
The promote-channels job moves the Docker Hub floating tags and the
GitHub "Latest" release after publish-github. All release tags share
its concurrency group, so an older release that finishes last cannot
move a channel back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Release channels and Docker tags can remain stale because higher tags block promotion even when publication fails, and the shared concurrency lock can discard pending promotions.

1 open issue
1 previously missed issue

In code that hasn't changed since last review

Medium severity Failed higher-version tags can block promotion of published releases

.github/​scripts/​release-channels.sh:11

A higher tag can block promotion even if that release never publishes successfully. For example, if v1.40.2 is tagged while 1.40.1 finishes publishing and the 1.40.2 build fails, all three 1.40.1 channels are skipped and remain on an older release. Compare published, non-draft, non-prerelease releases instead of tags, retaining VERSION as a candidate.

1 resolved since last review

Review effort: Balanced

Comment thread .github/workflows/release.yml Resolved
The release-channels concurrency group uses queue: max, so a new
release does not cancel a waiting promotion. The channel script reads
the published releases, so a tag whose release failed does not stop a
lower release from moving its channels.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Cross-release serialization and GitHub/Docker Hub channel promotion require end-to-end validation of overlapping releases and failed-job reruns, which the described scratch setup and review environment cannot verify.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Linked end-to-end results are still needed to verify concurrent-release serialization, coordinated GitHub/Docker Hub promotion, and downstream repository token access.

No open issues 🎉

Review effort: Balanced

cloudsmith-iduffy and others added 4 commits November 18, 2026 17:03
* origin/master:
  ci: use the standard cloudsmith-bot secret names (#628)
Replace release-channels.sh with release_channels.py. The script keeps
its inline metadata in the file header, and uv runs it. It gives the
same output as the shell script.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
release_channels.py reads the releases with requests, not the gh CLI.
The new promote_channels.py moves the GitHub "Latest" release and the
Docker Hub floating tags, so the workflow keeps no large shell block.
The script header gives examples of why a channel moves only for the
highest release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The update command changes move to the eng-15913-update branch, which
is stacked on this one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The CLI has no release candidates, so the release workflow does not
need a pre-release path. A tag that is not MAJOR.MINOR.PATCH now fails
promote-channels. promote_channels.py now also holds the channel check,
because the validate job no longer runs it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cloudsmith-iduffy
cloudsmith-iduffy marked this pull request as ready for review November 19, 2026 13:37

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

Tip: disable this comment in your organization's Code Review settings.

@cloudsmith-iduffy
cloudsmith-iduffy merged commit f0f0d9d into master Nov 19, 2026
25 checks passed
@cloudsmith-iduffy
cloudsmith-iduffy deleted the eng-15913 branch November 19, 2026 15:16
cloudsmith-iduffy added a commit that referenced this pull request Nov 19, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* origin/master:
  feat(ENG-15913): add a release channel for each major version (#627)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants