jeremylongshore / sentry-release-management

Skill Content

---
name: sentry-release-management
description: |
  Manage Sentry releases with versioning, commit association, and source map uploads.
  Use when creating releases, linking commits to errors, uploading release artifacts,
  monitoring release health, or cleaning up old releases.
  Trigger with phrases like "sentry release", "create sentry version",
  "sentry source maps", "sentry suspect commits", "release health".
allowed-tools: Read, Write, Edit, Bash(sentry-cli:*), Bash(npx:*), Bash(node:*), Bash(git:*), Grep
version: 1.0.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
compatible-with: claude-code, codex, openclaw
tags: [saas, sentry, releases, source-maps, ci-cd, versioning]

---
# Sentry Release Management

## Overview

Manage the full Sentry release lifecycle: create versioned releases, associate commits for suspect commit detection, upload source maps for readable stack traces, and monitor release health with crash-free rates and adoption metrics. Every production deploy should create a Sentry release so errors are grouped by version and regressions are caught immediately.

## Prerequisites

- **Sentry CLI** installed: `npm install -g @sentry/cli` (v2.x) or use `npx @sentry/cli`
- **Auth token** with `project:releases` and `org:read` scopes from [sentry.io/settings/auth-tokens/](https://sentry.io/settings/auth-tokens/)
- **Environment variables** set: `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT`
- **Source maps** generated by your build (e.g., `tsc --sourceMap`, Vite `build.sourcemap: true`)
- **GitHub/GitLab integration** installed in Sentry for automatic commit association (Settings > Integrations)

## Instructions

### Step 1 — Create a Release and Associate Commits

Choose a release naming convention. Sentry accepts any string, but two patterns dominate production usage:

**Semver naming** ties releases to your package version:

```bash
# Semver: my-app@2.1.0
VERSION="my-app@$(node -p "require('./package.json').version")"
sentry-cli releases new "$VERSION"
```

**Commit SHA naming** ties releases to exact deployments:

```bash
# SHA: my-app@a1b2c3d (short) or full 40-char SHA
VERSION="my-app@$(git rev-parse --short HEAD)"
sentry-cli releases new "$VERSION"
```

After creating the release, associate commits. This is what powers **suspect commits** — Sentry's ability to identify which commit likely caused a new issue by matching error stack frames to recently changed files:

```bash
# Auto-detect commits since last release (requires GitHub/GitLab integration)
sentry-cli releases set-commits "$VERSION" --auto

# Or specify a commit range manually
sentry-cli releases set-commits "$VERSION" \
  --commit "my-org/my-repo@from_sha..to_sha"
```

When `--auto` runs, Sentry walks the git log from the previous release's last commit to the current HEAD. It stores each commit's author, changed files, and message. When a new error arrives, Sentry matches the stack trace file paths against recently changed files and suggests the author as the likely owner.

### Step 2 — Upload Source Maps and Release Artifacts

Source maps let Sentry translate minified stack traces into original source code. Upload them **before** deploying — Sentry does not retroactively apply source maps to existing events.

```bash
# Upload all .js and .map files from dist/
sentry-cli sourcemaps upload \
  --release="$VERSION" \
  --url-prefix="~/static/js" \
  --validate \
  ./dist
```

The `--url-prefix` must match how your JS files are served. The `~/` prefix is a wildcard that matches any scheme and host:

| Your script URL | Correct `--url-prefix` |
|-----------------|----------------------|
| `https://example.com/static/js/app.js` | `~/static/js` |
| `https://cdn.example.com/assets/bundle.js` | `~/assets` |
| `https://example.com/app.js` (root) | `~/` |

For multiple output directories (e.g., SSR apps):

```bash
sentry-cli sourcemaps upload \
  --release="$VERSION" \
  --url-prefix="~/" \
  ./dist/client ./dist/server
```

**Managing release artifacts** — list, inspect, and clean up uploaded files:

```bash
# List all artifacts for a release
sentry-cli releases files "$VERSION" list

# Delete all source maps for a release (free storage)
sentry-cli releases files "$VERSION" delete --all

# Upload a single file manually
sentry-cli releases files "$VERSION" upload ./dist/app.js.map
```

**Build tool plugins** (alternative to CLI uploads) — handle release creation, commit association, and source map upload automatically:

```typescript
// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default {
  build: { sourcemap: true },
  plugins: [
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      release: { name: process.env.VERSION },
      sourcemaps: {
        assets: './dist/**',
        filesToDeleteAfterUpload: ['./dist/**/*.map'],
      },
    }),
  ],
};
```

### Step 3 — Finalize, Deploy, and Monitor Release Health

**Finalize** marks the release as complete. Until finalized, the release appears as "unreleased" in the UI:

```bash
sentry-cli releases finalize "$VERSION"
```

Finalizing affects three things: (1) issues resolved as "next release" are marked resolved, (2) the release becomes the baseline for future `--auto` commit detection, and (3) the activity timeline records the release.

**Record the deployment** to track which environments run which release:

```bash
sentry-cli releases deploys "$VERSION" new \
  --env production \
  --started $(date +%s) \
  --finished $(date +%s)

# For staging
sentry-cli releases deploys "$VERSION" new --env staging
```

**Match the SDK release** — the `release` string in your Sentry SDK init **must** match the CLI version exactly, or events will not associate with the release:

```typescript
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  release: process.env.SENTRY_RELEASE,    // Must match CLI $VERSION exactly
  environment: process.env.NODE_ENV,
});
```

**Release health dashboard** — after deployment, monitor these metrics at `sentry.io/releases/`:

- **Crash-free rate**: Percentage of sessions without a fatal error. Target > 99.5%.
- **Adoption**: Percentage of total sessions running this release. Tracks rollout progress.
- **Sessions**: Total session count. A session begins when a user starts the app and ends after inactivity or a crash.
- **Error count**: New errors first seen in this release versus regressions.

Enable session tracking in the SDK for release health data:

```typescript
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  release: process.env.SENTRY_RELEASE,
  autoSessionTracking: true,   // Enabled by default in browser SDK
});
```

**Cleanup old releases** to manage storage and reduce noise:

```bash
# Delete a release and all its artifacts
sentry-cli releases delete "$VERSION"

# List all releases via API
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/releases/"
```

## Output

- Release created with a version identifier tied to semver or git SHA
- Commits associated for suspect commit detection and suggested assignees
- Source maps uploaded and validated for deobfuscated stack traces
- Release finalized with deployment environment and timestamps recorded
- SDK `release` value matching CLI version for event-to-release correlation
- Release health dashboard tracking crash-free rate, adoption, and session data

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `error: API request failed: 401` | Auth token invalid, expired, or missing `project:releases` scope | Regenerate at [sentry.io/settings/auth-tokens/](https://sentry.io/settings/auth-tokens/) with `project:releases` + `org:read` |
| `No commits found` with `--auto` | GitHub/GitLab integration not installed in Sentry | Install at Settings > Integrations > GitHub, then grant repo access |
| Source maps not resolving | `--url-prefix` does not match actual script URLs | Open browser DevTools Network tab, copy the script URL, and set `--url-prefix` to match the path portion |
| Stack traces still minified | Source maps uploaded after errors were captured | Upload source maps **before** deploying — Sentry does not retroactively apply them to existing events |
| `release already exists` | Re-creating a release that was already finalized | Non-fatal: use `set-commits` and `sourcemaps upload` to update it, or use a new version string |
| `release not found` in SDK events | `Sentry.init({ release })` does not match CLI version | Print both values and compare — they must be identical strings (case-sensitive) |
| Crash-free rate not appearing | Session tracking disabled | Verify `autoSessionTracking: true` in SDK init (default in browser SDKs, must be enabled in Node.js) |

See [errors reference](references/errors.md) for additional troubleshooting.

## Examples

**Complete release script for CI/CD:**

```bash
#!/bin/bash
# scripts/sentry-release.sh — run after build, before deploy
set -euo pipefail

VERSION="${1:-my-app@$(node -p "require('./package.json').version")}"
ENVIRONMENT="${2:-production}"

echo "Creating Sentry release: $VERSION → $ENVIRONMENT"

sentry-cli releases new "$VERSION"
sentry-cli releases set-commits "$VERSION" --auto
sentry-cli sourcemaps upload \
  --release="$VERSION" \
  --url-prefix="~/static/js" \
  --validate \
  ./dist
sentry-cli releases finalize "$VERSION"
sentry-cli releases deploys "$VERSION" new --env "$ENVIRONMENT"

echo "Release $VERSION deployed to $ENVIRONMENT"
```

**Monorepo with multiple Sentry projects:**

```bash
# Each service gets its own release prefix
sentry-cli releases new "api@$SHA" --project api-backend
sentry-cli releases new "web@$SHA" --project web-frontend

# Upload source maps per project
SENTRY_PROJECT=api-backend sentry-cli sourcemaps upload --release="api@$SHA" ./api/dist
SENTRY_PROJECT=web-frontend sentry-cli sourcemaps upload --release="web@$SHA" ./web/dist
```

**Query release health via API:**

```bash
# Get release health stats
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/releases/$VERSION/" \
  | jq '{version: .version, dateCreated: .dateCreated, commitCount: .commitCount, newGroups: .newGroups}'
```

See [examples reference](references/examples.md) for more patterns.

## Resources

- [Sentry Release Management (CLI)](https://docs.sentry.io/cli/releases/) — `sentry-cli releases` command reference
- [Source Map Uploads (CLI)](https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/cli/) — upload, validate, and debug source maps
- [Vite Plugin](https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/vite/) — `@sentry/vite-plugin` configuration
- [Webpack Plugin](https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/webpack/) — `@sentry/webpack-plugin` configuration
- [Releases Product Overview](https://docs.sentry.io/product/releases/) — UI walkthrough, suspect commits, suggested assignees
- [Release Health](https://docs.sentry.io/product/releases/health/) — crash-free rate, adoption, and session tracking
- [Sentry API: Releases](https://docs.sentry.io/api/releases/) — REST API for programmatic release management

## Next Steps

- Set up **CI/CD integration** to automate releases on every deploy — use the `sentry-ci-integration` skill
- Configure **performance tracing** alongside releases to correlate deploys with latency changes — use the `sentry-performance-tracing` skill
- Add **deploy notifications** to Slack/PagerDuty via Sentry's integration alerts
- Review **release health** after each deploy: aim for > 99.5% crash-free sessions before promoting to wider rollout
- Use `sentry-cli releases propose-version` in scripts to auto-generate version strings from git state