[wrangler] Add --tag support to versions deploy

[james-elicx]

Production deploys are commonly tagged with the commit SHA via wrangler versions deploy --tag <sha> (or at upload time). When rolling back, developers think in commit SHAs, but wrangler versions deploy only accepts CF Version IDs — so a rollback requires first running wrangler versions list to map a commit SHA to a Version ID.

This adds a --tag flag to wrangler versions deploy so you can deploy a version by its tag directly:

wrangler versions deploy --tag <sha>@100%

The tag is resolved to a Version ID by matching the workers/tag annotation against the worker's deployable versions. The <tag>@<percentage> shorthand mirrors the existing <version-id>@<percentage> notation, and multiple --tag values can be used to split traffic (and --tag can be combined with explicit Version IDs).

Behaviour notes:

• If a tag matches no deployable version, the command errors and points to wrangler versions list.
• If a tag matches more than one version, the command errors and lists the matching Version IDs so you can disambiguate by deploying with a Version ID directly.
• Tags can only be resolved against recent (deployable) versions — versions that have aged out of the deployable window must still be deployed by Version ID.

The deployable-versions fetch populates the existing version cache, so the subsequent prompt/deploy flow reuses it without extra API round-trips.

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: this PR is an initial draft for review; a Cloudflare docs update for the new --tag flag will follow before it ships.

[changeset-bot]

🦋 Changeset detected

Latest commit: edd87ae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
wrangler	Minor
@cloudflare/vite-plugin	Patch
@cloudflare/vitest-pool-workers	Patch
@cloudflare/wrangler-bundler	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[ask-bonk]

I've completed a thorough review. The implementation is well-structured, consistent with the existing --version-id/--version-spec patterns, and has comprehensive test coverage (single tag, multiple tags, combined with version ID, not-found, ambiguous, plus unit tests for parseTagSpecs).

The edge cases I found — tag/version-id collision silently overwriting an explicit percentage, duplicate --tag overwriting, and multi-@ splitting — are all genuine but very low-severity scenarios that represent user misuse and don't affect the documented happy paths or the core correctness. None rise to the level of a logic bug, security issue, backward-compat violation, or incorrect API behavior in normal use. Per the guidance to be pragmatic and not nitpick, these don't warrant blocking comments.

LGTM

github run

[github-actions]

✅ All changesets look good

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@14211

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@14211

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@14211

miniflare

npm i https://pkg.pr.new/miniflare@14211

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@14211

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@14211

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@14211

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@14211

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@14211

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@14211

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@14211

wrangler

npm i https://pkg.pr.new/wrangler@14211

@cloudflare/wrangler-bundler

npm i https://pkg.pr.new/@cloudflare/wrangler-bundler@14211

commit: edd87ae

[workers-devprod]

Codeowners approval required for this PR:

• @cloudflare/wrangler

Show detailed file reviewers

• .changeset/versions-deploy-by-tag.md: [@cloudflare/wrangler]
• packages/wrangler/src/tests/versions/versions.deploy.test.ts: [@cloudflare/wrangler]
• packages/wrangler/src/versions/deploy.ts: [@cloudflare/wrangler]

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.