Releases & Health

A release is a version of your code that is deployed to an environment. When you give Sentry information about your releases, you can:

• Determine issues and regressions introduced in a new release
• Predict which commit caused an issue and who is likely responsible
• Resolve issues by including the issue number in your commit message
• Receive email notifications when your code gets deployed

Bind the Version

Include a release ID (often called a "version") when you initialize the SDK.

The release name cannot:

• contain newlines, tabulator characters, forward slashes(/) or back slashes(\)
• be (in their entirety) period (.), double period (..), or space ( )
• exceed 200 characters

The value can be arbitrary, but we recommend either of these naming strategies:

• Semantic Versioning: package@version or package@version+build (for example, my.project.name@2.3.12+1234)
  • package is the unique identifier of the project/app (CFBundleIdentifier on iOS, packageName on Android)
  • version is the semver-like structure <major>.<minor?>.<patch?>.<revision?>-<prerelease?> (CFBundleShortVersionString on iOS, versionName on Android)
  • build is the number that identifies an iteration of your app (CFBundleVersion on iOS, versionCode on Android)
• Commit SHA: If you use a version control system like Git, we recommend using the identifying hash (for example, the commit SHA, da39a3ee5e6b4b0d3255bfef95601890afd80709). You can let Sentry CLI automatically determine this hash for supported version control systems. Learn more in our Sentry CLI documentation.

The behavior of a few features depends on whether a project is using semantic or time-based versioning.

• Regression detection
• release:latest

We automatically detect whether a project is using semantic or time-based versioning based on:

• If ≤ 2 releases total: we look at most recent release.
• If 3-9 releases (inclusive): if any of the most recent 3 releases is semver, project is semver.
• If 10 or more releases: if any of the most recent 3 releases is semver, and 3 out of the most recent 10 releases is semver, then the project is semver.

Setting a Release

sentry:
  options:
    release: "my-project-name@2.3.12"

How you make the release name (or version) available to your code is up to you. For example, you could use an environment variable that is set during the build process or during initial start-up.

Setting the release name tags each event with that release name. We recommend that you tell Sentry about a new release before sending events with that release name, as this will unlock a few more features. Learn more in our Releases documentation.

If you don't tell Sentry about a new release, Sentry will automatically create a release entity in the system the first time it sees an event with that release ID.

After configuring your SDK, you can install a repository integration or manually supply Sentry with your own commit metadata. Read our documentation about setting up releases for further information about integrations, associating commits, and telling Sentry when deploying releases.