Track deployments and release health in Sentry.
Use when configuring deployment tracking, release health monitoring,
or connecting CI/CD deploys to error data in Sentry.
Trigger with phrases like "sentry deploy tracking", "sentry release health",
"track deployments sentry", "sentry deployment notification",
"sentry suspect commits", "compare sentry releases".
Track deployments and release health in Sentry.
Use when configuring deployment tracking, release health monitoring,
or connecting CI/CD deploys to error data in Sentry.
Trigger with phrases like "sentry deploy tracking", "sentry release health",
"track deployments sentry", "sentry deployment notification",
"sentry suspect commits", "compare sentry releases".
Wire Sentry into your deploy pipeline so every release is tracked end-to-end: commit association, source map upload, deploy recording, and post-deploy health monitoring. Sentry links errors to the exact deploy and suspect commit that introduced them, giving you crash-free session rates, adoption curves, and regression alerts per release.
Prerequisites
Sentry CLI installed (npm i -g @sentry/cli or curl -sL https://sentry.io/get-cli/ | bash)
SENTRY_AUTH_TOKEN with project:releases and org:read scopes
SENTRY_ORG and SENTRY_PROJECT environment variables set
@sentry/node v8+ installed in your application
Source control integration enabled in Sentry (Settings > Integrations > GitHub/GitLab)
Instructions
Step 1 --- Record Deploys with sentry-cli
Create a release, associate commits for suspect-commit linking, and record the deployment with timing metadata.
#!/bin/bash# scripts/sentry-deploy.shset -euo pipefail
VERSION="${1:-$(sentry-cli releases propose-version)}"
ENVIRONMENT="${2:-production}"
DEPLOY_START=$(date +%s)
# Create release and associate commits (enables suspect commits)
sentry-cli releases new "$VERSION"
sentry-cli releases set-commits "$VERSION" --auto
# Upload source maps for readable stack traces
sentry-cli sourcemaps upload \
--release="$VERSION" \
--url-prefix="~/static/js" \
--validate \
./dist
# Finalize marks the release as ready
sentry-cli releases finalize "$VERSION"# --- Deploy your application here ---# e.g., kubectl set image deployment/app app=myapp:$VERSION
DEPLOY_END=$(date +%s)
sentry-cli releases deploys new \
-e \
-t \
-f
For multi-environment promotion (staging then production):
# Stage 1: deploy to staging
sentry-cli releases deploys "$VERSION" new -e staging
# Stage 2: after QA passes, deploy to production
sentry-cli releases deploys "$VERSION" new -e production
# Sentry dashboard shows the full promotion timeline
Step 2 --- Tag Releases in the SDK and Monitor Health
Configure the Sentry SDK with the release tag so crash-free session/user metrics, adoption rates, and error attribution bind to each release.
// src/instrument.tsimport * asSentryfrom'@sentry/node';
Sentry.init({
dsn: process.env.SENTRY_DSN,
release: process.env.SENTRY_RELEASE, // e.g. "my-app@1.4.2"environment: process.env.NODE_ENV, // "production" | "staging"// Release health: session tracking is on by default in v8// Crash-free sessions/users calculated automatically// Sample 10% of transactions in productiontracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,
});
Release health metrics Sentry tracks automatically:
Metric
What it measures
Crash-free sessions
% of sessions with zero unhandled errors
Crash-free users
% of distinct users with zero unhandled errors
Adoption
% of sessions on this release vs. the previous release
Error count
New and total errors attributed to this release
Session count
Total sessions observed on this release
Step 3 --- Compare Releases, Detect Regressions, and Configure Notifications
Compare releases via the API to catch regressions before they spread:
# List recent releases with new-issue counts and deploy info
curl -s \
-H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
"https://sentry.io/api/0/organizations/$SENTRY_ORG/releases/?project=$SENTRY_PROJECT&per_page=5&health=1" \
| python3 -c "
import json, sys
releases = json.load(sys.stdin)
for r in releases:
health = r.get('healthData', {})
crash_free = health.get('crashFreeSessions', 'N/A')
new_issues = r.get('newGroups', 0)
deploys = len(r.get('deploys', []))
print(f\"{r['version']}: {new_issues} new issues, {deploys} deploys, crash-free: {crash_free}\")
"
Suspect commits --- when set-commits is configured, Sentry traces each new error to the commit that likely introduced it:
# Fetch suspect commits for a specific issue
curl -s \
-H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
"https://sentry.io/api/0/issues/$ISSUE_ID/committers/" \
| python3 -c "
import json, sys
data = json.load(sys.stdin)
for c in data.get('committers', []):
author = c['author']['name']
for commit in c['commits']:
print(f\" Suspect: {commit['id'][:8]} by {author} — {commit['message'].splitlines()[0]}\")
"
Deploy notification webhooks --- configure in Project Settings > Integrations > Internal Integrations or use the webhook directly:
Rollback tracking --- record the rollback as a new deploy pointing to the previous stable version:
ROLLBACK_TO="my-app@1.3.9"
sentry-cli releases deploys "$ROLLBACK_TO" new \
-e production \
--name "Rollback from $CURRENT_VERSION"# Sentry attributes new errors to the rolled-back version
Output
After completing these steps you will have:
Every deploy recorded in Sentry with environment and timestamps
Crash-free session and user rates tracked per release
Adoption curves showing rollout progress
Suspect commits linking new errors to the exact commit that introduced them
Release comparison showing regression counts across versions
Deploy notifications flowing to Slack, PagerDuty, or custom webhooks
Rollback events visible in the release timeline
Error Handling
Error
Cause
Solution
error: release not found
Deploy created before release exists
Run sentry-cli releases new $VERSION before recording the deploy
No release health data
Session tracking disabled or SDK < v7.2
Upgrade to @sentry/node v8+; do not set autoSessionTracking: false
Wrong environment on events
environment not set in SDK init
Pass environment explicitly in Sentry.init()
Suspect commits missing
Source control integration not linked
Enable GitHub/GitLab in Settings > Integrations and run set-commits --auto
401 Unauthorized on deploy API
Token missing project:releases scope
Regenerate token at https://sentry.io/settings/account/api/auth-tokens/
Crash-free rate stuck at 100%
Release tag mismatch between CLI and SDK
Ensure SENTRY_RELEASE in Sentry.init() matches the sentry-cli releases new version exactly
Deploy timestamps zero
Missing -t/-f flags on deploys new
Capture $(date +%s) before and after deploy, pass both flags
Examples
TypeScript: Full deploy script with health check polling
