sentry-release-management
Use when managing Sentry releases, uploading source maps, or tracking deployments. Covers release health and commit association.
When & Why to Use This Skill
This Claude skill streamlines Sentry release management by automating version creation, source map uploads, and deployment tracking. It enables developers to associate commits with releases, monitor release health metrics like crash-free sessions, and integrate Sentry seamlessly into CI/CD pipelines and modern build tools like Webpack, Vite, and Next.js for enhanced error debugging and stability monitoring.
Use Cases
- Automated CI/CD Integration: Streamline the creation, commit association, and finalization of Sentry releases within GitHub Actions or GitLab CI pipelines.
- Source Map Management: Automatically upload and validate source maps for JavaScript frameworks to ensure production error stack traces are mapped correctly to original source code.
- Release Health Monitoring: Track real-time metrics such as crash-free user percentages and session counts to evaluate the stability of new versions during rollout.
- Deployment Tracking: Create and manage deployment records across different environments (e.g., production, staging) to identify exactly when and where code changes were deployed.
| name | sentry-release-management |
|---|---|
| description | Use when managing Sentry releases, uploading source maps, or tracking deployments. Covers release health and commit association. |
Sentry - Release Management
Manage releases, upload source maps, and track deployments.
Creating Releases
Using sentry-cli
# Create a new release
sentry-cli releases new "$VERSION"
# Associate commits
sentry-cli releases set-commits "$VERSION" --auto
# Finalize the release
sentry-cli releases finalize "$VERSION"
In CI/CD
# GitHub Actions
- name: Create Sentry Release
uses: getsentry/action-release@v1
env:
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_ORG: your-org
SENTRY_PROJECT: your-project
with:
environment: production
version: ${{ github.sha }}
GitLab CI
release:
stage: deploy
script:
- sentry-cli releases new "$CI_COMMIT_SHA"
- sentry-cli releases set-commits "$CI_COMMIT_SHA" --auto
- sentry-cli releases finalize "$CI_COMMIT_SHA"
- sentry-cli releases deploys "$CI_COMMIT_SHA" new -e production
Source Maps
Upload Source Maps
# Upload source maps for a release
sentry-cli sourcemaps upload \
--release="$VERSION" \
--url-prefix="~/" \
./dist
# With validation
sentry-cli sourcemaps upload \
--release="$VERSION" \
--validate \
./dist
Webpack Plugin
// webpack.config.js
const { sentryWebpackPlugin } = require("@sentry/webpack-plugin");
module.exports = {
devtool: "source-map",
plugins: [
sentryWebpackPlugin({
org: "your-org",
project: "your-project",
authToken: process.env.SENTRY_AUTH_TOKEN,
release: {
name: process.env.RELEASE_VERSION,
},
sourcemaps: {
assets: "./dist/**",
},
}),
],
};
Vite Plugin
// vite.config.ts
import { sentryVitePlugin } from "@sentry/vite-plugin";
export default defineConfig({
build: {
sourcemap: true,
},
plugins: [
sentryVitePlugin({
org: "your-org",
project: "your-project",
authToken: process.env.SENTRY_AUTH_TOKEN,
}),
],
});
Next.js
// next.config.js
const { withSentryConfig } = require("@sentry/nextjs");
module.exports = withSentryConfig(nextConfig, {
org: "your-org",
project: "your-project",
authToken: process.env.SENTRY_AUTH_TOKEN,
silent: true,
hideSourceMaps: true,
});
Deployments
# Create a deployment
sentry-cli releases deploys "$VERSION" new \
--env production \
--started $(date +%s) \
--finished $(date +%s)
Release Health
Track in SDK
Sentry.init({
dsn: "...",
release: "my-app@1.2.3",
environment: "production",
autoSessionTracking: true,
});
Metrics Tracked
- Crash-Free Sessions: Percentage of sessions without crashes
- Crash-Free Users: Percentage of users without crashes
- Session Count: Total sessions for the release
- Adoption: User adoption rate
Configuration Files
.sentryclirc
[defaults]
org = your-org
project = your-project
[auth]
token = your-auth-token
sentry.properties
defaults.org=your-org
defaults.project=your-project
auth.token=your-auth-token
Best Practices
- Use semantic versioning for releases
- Associate commits for suspect commits feature
- Upload source maps before deploying
- Create deployments to track where releases run
- Monitor release health before full rollout
- Delete old source maps to manage storage
- Use CI/CD integration for automated releases
Cleanup
# Delete old releases
sentry-cli releases delete "$OLD_VERSION"
# Delete source maps (keeps release)
sentry-cli releases files "$VERSION" delete --all