feat(release): add release command group and CI finalization

[BYK]

Summary

Adds the sentry release command group — the #1 critical gap identified in #600 — with 10 subcommands for full release lifecycle management, plus a GitHub Actions workflow for automated release finalization.

Commands

Command	Description
release list	Paginated org-scoped release listing
release view	Release detail view
release create	Create with --project, --finalize, --ref, --url, --dry-run
release finalize	Set dateReleased (custom timestamp via --released), --dry-run
release delete	buildDeleteCommand — auto --yes/--force/--dry-run, type-to-confirm
release deploy	Positional <version> <environment> [name], --time, --dry-run
release deploys	List deploys for a release
release set-commits	--auto, --local, --commit REPO@SHA (ranges: REPO@PREV..SHA), --clear
release propose-version	Detect from 15 CI env vars (GitHub, Vercel, Heroku, etc.) or git HEAD
releases (alias)	→ release list

Key design decisions

• buildDeleteCommand for release delete — auto-injects --yes/--force/--dry-run flags, non-interactive guard, uses confirmByTyping from shared infrastructure
• DRY_RUN_FLAG on create, finalize, deploy — consistent --dry-run/-n support across all mutation commands
• --commit supports ranges — REPO@PREV..SHA sends refs format to the API, matching the reference sentry-cli
• set-commits default mode — tries auto-discovery, falls back to local git with warning. Per-org negative cache in the metadata table (1-hour TTL) skips the speculative API call on subsequent runs
• No simple-git dependency — execFileSync (no shell) from node:child_process for all git operations. Avoids shell injection and works natively in both Bun and Node distributions
• @sentry/api types — uses OrgReleaseResponse and DeployResponse directly from the SDK instead of redundant Zod schemas
• Centralized git helpers — src/lib/git.ts consolidates primitives used by both release commands and sentry init wizard. src/lib/init/git.ts is now a thin adapter
• propose-version checks 15 CI env vars (matching the reference impl) before falling back to git HEAD

CI integration

.github/workflows/sentry-release.yml — triggered on release: published, installs the just-published npm package via npm install -g sentry@$VERSION, then runs create → set-commits → finalize → deploy.

Testing

• Property-based tests for parseReleaseArg and parseRemoteUrl (fast-check)
• Unit tests for view, create, finalize, deploy, propose-version, set-commits commands
• API tests with globalThis.fetch mocking for all 11 exported API functions
• 83 tests, 11,778 assertions

New files (35 changed, +3913 / -103)

• src/lib/git.ts — centralized git helpers (execFileSync, no shell)
• src/lib/api/releases.ts — 11 API functions
• src/commands/release/ — 10 command files + arg parser
• .github/workflows/sentry-release.yml — CI finalization workflow
• test/ — 10 test files

Ref: #600

[github-actions]

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

New Features ✨

Telemetry

• Add cache hit rate metric across all cache systems by BYK in #638
• Add performance instrumentation and CLI Performance dashboard by BYK in #625
• Upgrade Sentry SDK to 10.47.0 and enable runtime metrics by BYK in #622

Other

• (auth) Show token expiry in days/weeks instead of raw hours by BYK in #620
• (ci) Add delta patch generation for stable releases by BYK in #618
• (commands) Add shared helpers and buildDeleteCommand for mutation commands by BYK in #639
• (dashboard) Render text widget markdown content in dashboard view by BYK in #624

• (release) Add release command group and CI finalization by BYK in #628

• (traces) Expose custom span attributes and improve agent guidance by BYK in #623
• Improve unknown command UX with aliases, default routing, and suggestions by BYK in #635

Bug Fixes 🐛

Telemetry

• Exclude OutputError from Sentry exception capture (CLI-PK) by BYK in #629
• Derive environment from CLI_VERSION instead of NODE_ENV by BYK in #627

Other

• (build) Use esbuild for binary bundling to fix minifier collision bug by BYK in #619
• (ci) Restore GH_TOKEN for gh CLI steps in generate-patches by BYK in #634
• (init) Prompt for team selection when user belongs to multiple teams by betegon in #621
• (polyfill) Add missing Bun API polyfills for npm distribution by BYK in #637
• (upgrade) Remove "What's new" header from changelog output by BYK in #626

Documentation 📚

• Add tracemetrics dataset guidance and validate aggregate format by BYK in #636

Internal Changes 🔧

• (deps) Upgrade @sentry/api from 0.54.0 to 0.94.0 by BYK in #630
• Remove stale debug-level stderr assertions and fix logger state leak by BYK in #631
• Regenerate skill files and command docs by github-actions[bot] in e01b2520

---

_{🤖 This preview updates automatically when you update the PR.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/pr-preview/pr-628/
Built to branch gh-pages at 2026-04-02 14:55 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

✅ 129 passed | Total: 129 | Pass Rate: 100% | Execution Time: 0ms

📊 Comparison with Base Branch

Metric	Change
Total Tests	—
Passed Tests	—
Failed Tests	—
Skipped Tests	—

✨ No test changes detected

All tests are passing successfully.

✅ Patch coverage is 97.72%. Project has 1385 uncovered lines.
✅ Project coverage is 95.59%. Comparing base (base) to head (head).

Files with missing lines (1)

File	Patch %	Lines
src/lib/api/releases.ts	86.62%	⚠️ 21 Missing

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    95.51%    95.59%    +0.08%
==========================================
  Files          206       219       +13
  Lines        30469     31382      +913
  Branches         0         0         —
==========================================
+ Hits         29101     29997      +896
- Misses        1368      1385       +17
- Partials         0         0         —

---

Generated by Codecov Action

[BYK]

Will --auto work without a checkout?

[BYK]

Yes — --auto uses the Sentry repo integration (server-side API). It sends refs: [{repository: "auto", commit: "auto"}] to the releases API, which tells Sentry to discover commits via the linked GitHub/GitLab integration. No local git repo or checkout needed.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Missing null guard on lastDeploy.dateFinished before formatting

Low Severity

release.lastDeploy.dateFinished is passed directly to formatRelativeTime without a truthiness check. The DeployResponse type allows dateFinished to be null (as seen in test fixtures). Both deploy.ts and deploys.ts in this same PR consistently guard with a ternary (d.dateFinished ? formatRelativeTime(d.dateFinished) : "—") before calling the formatter. Here, a null dateFinished produces "production (—)" — a dash wrapped in parentheses — which is an awkward display compared to the clean fallback used elsewhere.

Additional Locations (2)

• src/commands/release/deploy.ts#L43-L46
• src/commands/release/deploys.ts#L21-L24