> ## Documentation Index
> Fetch the complete documentation index at: https://sentrydocs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# 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`).

<Tip>
  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.
</Tip>

### Using the API

```bash theme={null}
# 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 theme={null}
// JavaScript
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  release: "my-app@2.4.1",
});
```

```python theme={null}
# Python
import sentry_sdk

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/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.

```bash theme={null}
sentry-cli releases deploys "$VERSION" new \
  --env production \
  --name "Production deploy 2024-03-15"
```

Or via the API:

```bash theme={null}
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.

<CardGroup cols={2}>
  <Card title="Crash-free sessions" icon="shield-check">
    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.
  </Card>

  <Card title="Crash-free users" icon="user-check">
    The percentage of unique users who did not experience a crash in the given release.
  </Card>
</CardGroup>

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.

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