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

.github/workflows/sentry-release.yml

@@ -0,0 +1,35 @@
+name: Sentry Release
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  finalize:
+    name: Finalize Sentry Release
+    runs-on: ubuntu-latest
+    # Skip pre-releases (nightlies, dev versions)
+    if: "!github.event.release.prerelease"
+    env:
+      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+      # Tag names are bare semver (e.g., "0.24.0", no "v" prefix),
+      # matching both the npm package version and Sentry release version.
+      VERSION: ${{ github.event.release.tag_name }}
+    steps:
+      - name: Install CLI
+        run: npm install -g "sentry@${VERSION}"
+
+      - name: Create release
+        run: sentry release create "sentry/${VERSION}" --project cli
+
+      - name: Set commits
+        continue-on-error: true
+        run: sentry release set-commits "sentry/${VERSION}" --auto
+
+      - name: Finalize release
+        run: sentry release finalize "sentry/${VERSION}"
+
+      - name: Create deploy
+        run: sentry release deploy "sentry/${VERSION}" production

AGENTS.md

@@ -61,6 +61,14 @@ bun run test:unit                        # Run unit tests only
 bun run test:e2e                         # Run e2e tests only
 ```
 
+## Rules: No Runtime Dependencies
+
+**CRITICAL**: All packages must be in `devDependencies`, never `dependencies`. Everything is bundled at build time via esbuild. CI enforces this with `bun run check:deps`.
+
+When adding a package, always use `bun add -d <package>` (the `-d` flag).
+
+When the `@sentry/api` SDK provides types for an API response, import them directly from `@sentry/api` instead of creating redundant Zod schemas in `src/types/sentry.ts`.
+
 ## Rules: Use Bun APIs
 
 **CRITICAL**: This project uses Bun as runtime. Always prefer Bun-native APIs over Node.js equivalents.
@@ -1038,4 +1046,7 @@ mock.module("./some-module", () => ({
 
 <!-- lore:019d3f09-d39b-7795-b8a0-4a3e58a996f9 -->
 * **validateWidgetEnums skipDeprecatedCheck for edit-path inherited datasets**: When editing a widget, \`effectiveDataset = flags.dataset ?? existing.widgetType\` may inherit a deprecated type (e.g., \`discover\`). The \`validateWidgetEnums\` deprecation check must be skipped for inherited values — only fire when the user explicitly passes \`--dataset\`. Solution: \`validateWidgetEnums(effectiveDisplay, effectiveDataset, { skipDeprecatedCheck: true })\` in \`edit.ts\`. The cross-validation between display type and dataset still runs on effective values, catching incompatible combos. The deprecation rejection helper \`rejectInvalidDataset()\` is extracted to keep \`validateWidgetEnums\` under Biome's complexity limit of 15.
+
+<!-- lore:019d5a00-0000-7000-a000-000000000001 -->
+* **set-commits default mode makes speculative --auto API call by design**: When \`release set-commits\` is called without \`--auto\` or \`--local\`, it tries auto-discovery first and falls back to local git on 400 error. This matches the reference sentry-cli behavior (parity-correct). A per-org negative cache in the \`metadata\` table (\`repos_configured.<org>\` = \`"false"\`, 1-hour TTL) skips the speculative auto call on subsequent runs when no repo integration is configured. The cache clears on successful auto-discovery.
 <!-- End lore-managed section -->

docs/public/.well-known/skills/index.json

@@ -13,6 +13,7 @@
         "references/logs.md",
         "references/organizations.md",
         "references/projects.md",
+        "references/release.md",
         "references/setup.md",
         "references/sourcemap.md",
         "references/teams.md",

docs/src/content/docs/commands/index.md

@@ -14,6 +14,7 @@ The Sentry CLI provides commands for interacting with various Sentry resources.
 | [`dashboard`](./dashboard/) | Manage Sentry dashboards |
 | [`org`](./org/) | Work with Sentry organizations |
 | [`project`](./project/) | Work with Sentry projects |
+| [`release`](./release/) | Work with Sentry releases |
 | [`repo`](./repo/) | Work with Sentry repositories |
 | [`team`](./team/) | Work with Sentry teams |
 | [`issue`](./issue/) | Manage Sentry issues |

docs/src/content/docs/commands/release.md

@@ -0,0 +1,192 @@
+---
+title: release
+description: Release commands for the Sentry CLI
+---
+
+Work with Sentry releases
+
+## Commands
+
+### `sentry release list <org/project>`
+
+List releases
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/project>` | &lt;org&gt;/ (all projects), &lt;org&gt;/&lt;project&gt;, or &lt;project&gt; (search) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-n, --limit <limit>` | Maximum number of releases to list (default: "30") |
+| `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
+| `-c, --cursor <cursor>` | Navigate pages: "next", "prev", "first" (or raw cursor string) |
+
+### `sentry release view <org/version...>`
+
+View release details
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/version...>` | [&lt;org&gt;/]&lt;version&gt; - Release version to view |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
+
+### `sentry release create <org/version...>`
+
+Create a release
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/version...>` | [&lt;org&gt;/]&lt;version&gt; - Release version to create |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-p, --project <project>` | Associate with project(s), comma-separated |
+| `--finalize` | Immediately finalize the release (set dateReleased) |
+| `--ref <ref>` | Git ref (branch or tag name) |
+| `--url <url>` | URL to the release source |
+| `-n, --dry-run` | Show what would happen without making changes |
+
+### `sentry release finalize <org/version...>`
+
+Finalize a release
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/version...>` | [&lt;org&gt;/]&lt;version&gt; - Release version to finalize |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--released <released>` | Custom release timestamp (ISO 8601). Defaults to now. |
+| `--url <url>` | URL for the release |
+| `-n, --dry-run` | Show what would happen without making changes |
+
+### `sentry release delete <org/version...>`
+
+Delete a release
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/version...>` | [&lt;org&gt;/]&lt;version&gt; - Release version to delete |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-y, --yes` | Skip confirmation prompt |
+| `-f, --force` | Force the operation without confirmation |
+| `-n, --dry-run` | Show what would happen without making changes |
+
+### `sentry release deploy <org/version environment name...>`
+
+Create a deploy for a release
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/version environment name...>` | [&lt;org&gt;/]&lt;version&gt; &lt;environment&gt; [name] |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--url <url>` | URL for the deploy |
+| `--started <started>` | Deploy start time (ISO 8601) |
+| `--finished <finished>` | Deploy finish time (ISO 8601) |
+| `-t, --time <time>` | Deploy duration in seconds (sets started = now - time, finished = now) |
+| `-n, --dry-run` | Show what would happen without making changes |
+
+### `sentry release deploys <org/version...>`
+
+List deploys for a release
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/version...>` | [&lt;org&gt;/]&lt;version&gt; - Release version |
+
+### `sentry release set-commits <org/version...>`
+
+Set commits for a release
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/version...>` | [&lt;org&gt;/]&lt;version&gt; - Release version |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--auto` | Use repository integration to auto-discover commits |
+| `--local` | Read commits from local git history |
+| `--clear` | Clear all commits from the release |
+| `--commit <commit>` | Explicit commit as REPO@SHA or REPO@PREV..SHA (comma-separated) |
+| `--initial-depth <initial-depth>` | Number of commits to read with --local (default: "20") |
+
+### `sentry release propose-version`
+
+Propose a release version
+
+All commands support `--json` for machine-readable output and `--fields` to select specific JSON fields.
+
+<!-- GENERATED:END -->
+
+## Examples
+
+```bash
+# List releases (auto-detect org)
+sentry release list
+
+# List releases in a specific org
+sentry release list my-org/
+
+# View release details
+sentry release view 1.0.0
+sentry release view my-org/1.0.0
+
+# Create and finalize a release
+sentry release create 1.0.0 --finalize
+
+# Create a release, then finalize separately
+sentry release create 1.0.0
+sentry release set-commits 1.0.0 --auto
+sentry release finalize 1.0.0
+
+# Set commits from local git history
+sentry release set-commits 1.0.0 --local
+
+# Create a deploy
+sentry release deploy 1.0.0 production
+sentry release deploy 1.0.0 staging "Deploy #42"
+
+# Propose a version from git HEAD
+sentry release create $(sentry release propose-version)
+
+# Output as JSON
+sentry release list --json
+sentry release view 1.0.0 --json
+```

package.json

@@ -5,6 +5,7 @@
     "type": "git",
     "url": "git+https://github.com/getsentry/cli.git"
   },
+  "main": "./dist/index.cjs",
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
     "@biomejs/biome": "2.3.8",
@@ -43,18 +44,16 @@
     "wrap-ansi": "^10.0.0",
     "zod": "^3.24.0"
   },
-  "bin": {
-    "sentry": "./dist/bin.cjs"
-  },
-  "main": "./dist/index.cjs",
-  "types": "./dist/index.d.cts",
   "exports": {
     ".": {
       "types": "./dist/index.d.cts",
       "require": "./dist/index.cjs",
       "default": "./dist/index.cjs"
     }
   },
+  "bin": {
+    "sentry": "./dist/bin.cjs"
+  },
   "description": "Sentry CLI - A command-line interface for using Sentry built by robots and humans for robots and humans",
   "engines": {
     "node": ">=22"
@@ -94,5 +93,6 @@
     "check:deps": "bun run script/check-no-deps.ts",
     "check:errors": "bun run script/check-error-patterns.ts"
   },
-  "type": "module"
+  "type": "module",
+  "types": "./dist/index.d.cts"
 }

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -313,6 +313,22 @@ Manage Sentry dashboards
 
 → Full flags and examples: `references/dashboards.md`
 
+### Release
+
+Work with Sentry releases
+
+- `sentry release list <org/project>` — List releases
+- `sentry release view <org/version...>` — View release details
+- `sentry release create <org/version...>` — Create a release
+- `sentry release finalize <org/version...>` — Finalize a release
+- `sentry release delete <org/version...>` — Delete a release
+- `sentry release deploy <org/version environment name...>` — Create a deploy for a release
+- `sentry release deploys <org/version...>` — List deploys for a release
+- `sentry release set-commits <org/version...>` — Set commits for a release
+- `sentry release propose-version` — Propose a release version
+
+→ Full flags and examples: `references/release.md`
+
 ### Repo
 
 Work with Sentry repositories