Sentry Release Management Skill

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/
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:

# 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:

# 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:

# 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.

# 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):

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

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

# 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:

// 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:

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:

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:

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:

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:

# 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/ 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 for additional troubleshooting.

Examples

Complete release script for CI/CD:

#!/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:

# 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:

# 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 for more patterns.

Resources

Sentry Release Management (CLI) — sentry-cli releases command reference
Source Map Uploads (CLI) — upload, validate, and debug source maps
Vite Plugin — @sentry/vite-plugin configuration
Webpack Plugin — @sentry/webpack-plugin configuration
Releases Product Overview — UI walkthrough, suspect commits, suggested assignees
Release Health — crash-free rate, adoption, and session tracking
Sentry 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

Agent Skills: Sentry Release Management

Install this agent skill to your local

Skill Files