Releases

Track deployments and correlate issues with the code changes that introduced them.

A release in Sentry represents a specific version of your deployed code. By telling Sentry when you release new code, you can see which version introduced a bug, track how quickly users adopt updates, and monitor the health of each release over time.

What releases give you

• Suspect commits — Sentry uses commit data to identify which code changes likely introduced an issue
• Issue attribution — you can see “this issue first appeared in version 2.4.1”
• Release health — track crash-free session and crash-free user rates per release
• Deployment notifications — notify your team when a new version ships to an environment
• Resolve in next release — mark an issue resolved and have Sentry automatically reopen it if it recurs in a later release

Creating a release

You can create releases via the Sentry CLI or the Sentry API. Most teams do this as part of their CI/CD pipeline.

Using sentry-cli

# Install sentry-cli
npm install -g @sentry/cli

# Create a new release
sentry-cli releases new "$VERSION"

# Associate commits with the release
sentry-cli releases set-commits "$VERSION" --auto

# Mark the release as finalized (deployed)
sentry-cli releases finalize "$VERSION"

Replace $VERSION with your release identifier — a git SHA, tag, or semantic version string (e.g. 2.4.1 or abc123f).

Use --auto with set-commits to automatically detect commits from your local git repository. Alternatively, use --commit "repo-name@from-sha..to-sha" to specify a commit range explicitly.

Using the API

# Create a release
curl https://sentry.io/api/0/organizations/{org_slug}/releases/ \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "2.4.1",
    "projects": ["my-project"],
    "refs": [
      {
        "repository": "my-org/my-repo",
        "commit": "abc123f"
      }
    ]
  }'

Configuring the SDK

Set the release option when initializing the Sentry SDK so that all events captured include the release version:

// JavaScript
Sentry.init({
  dsn: "https://[e-mail]/0",
  release: "my-app@2.4.1",
});

# Python
import sentry_sdk

sentry_sdk.init(
    dsn="https://[e-mail]/0",
    release="my-app@2.4.1",
)

Associating commits

Linking commits to a release is what powers suspect commit detection. When Sentry knows which files changed between releases, it can identify the commits most likely to have introduced a regression.

To associate commits, you need to:

1. Connect your source code repository (GitHub, GitLab, Bitbucket, Azure DevOps) in Settings → Integrations
2. Pass commit information when creating the release, either via sentry-cli releases set-commits or the refs field in the API

Deploy notifications

A deploy records that a release was deployed to a specific environment. Creating a deploy triggers notifications to users who are subscribed to the repository’s commit activity.

sentry-cli releases deploys "$VERSION" new \
  --env production \
  --name "Production deploy 2024-03-15"

Or via the API:

curl https://sentry.io/api/0/organizations/{org_slug}/releases/{version}/deploys/ \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"environment": "production"}'

Release health

Release health gives you visibility into how stable each release is after deployment.

Crash-free sessions

The percentage of user sessions that did not end in a crash. A session starts when your app launches and ends when it goes to the background or crashes.

Crash-free users

The percentage of unique users who did not experience a crash in the given release.

Release health requires the Sentry SDK to be configured with session tracking. This is enabled by default in most mobile and frontend SDKs.

You can view release health on the Releases page, which shows a comparison across versions so you can immediately see if a new release is performing worse than its predecessor.

Resolving issues in a release

When you resolve an issue, you can choose Resolved in next release instead of just Resolved. If events for that issue appear in a later release, Sentry will automatically reopen it and mark it as a regression. This is especially useful when you’ve deployed a fix and want to confirm it worked.

Sentry can only detect regressions across releases if the release attribute is configured in your SDK and populated on incoming events.