Releases

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

  • Determine the 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

Additionally, releases are used for applying source maps to minified JavaScript to view original, untransformed source code.

Setting up Releases

Setting up releases fully is a 3-step process:

  1. Configure Your SDK
  2. Create Release and Associate Commits
  3. Tell Sentry When You Deploy a Release

Configure Your SDK

Include a release ID (a.k.a version) where you configure your client SDK. This is commonly a git SHA or a custom version number. Note that releases are global per organization so make sure to prefix them with something project specific if needed:

using Sentry;

SentrySdk.Init(o => o.Release = "my-project-name@2.3.12");
sentry.Init(sentry.ClientOptions{
	Release: "my-project-name@2.3.12",
})
Sentry.init({
  release: "my-project-name@2.3.12"
})
Sentry\init([
  'release' => 'my-project-name@2.3.12',
]);
import sentry_sdk

sentry_sdk.init(release="my-project-name@2.3.12")
use sentry;

sentry::init(sentry::ClientOptions {
    release: "my-project-name@2.3.12"
});

How you make the version available to your code is up to you. For example, you could use an environment variable that is set during the build process.

This annotates each error with the release. We recommend that you tell Sentry about a new release prior to deploying it as this will unlock a few more features (explained in Step 2) . But if you don’t, Sentry will automatically create a release entity in the system the first time it sees an error with that release ID.

After this, you should see information about the release, such as new issues and regressions introduced in the release.

Create Release and Associate Commits

In this step you tell Sentry about a new release and which commits are associated with it. This allows Sentry to pinpoint which commits likely caused an issue, and allow your team to resolve issues by referencing the issue number in a commit message.

There are two ways to create a release and associate commits: using a repository integration (recommended), or by manually supplying Sentry with your own commit metadata.

Using one of Sentry’s repository integrations (e.g. GitHub, GitLab, Bitbucket, etc.) is the easiest way to connect your commit metadata to Sentry. For a list of available integrations, go to Organization Settings > Integrations.

Once you are in Organization Settings > Integrations and have installed the integration, click the ‘Configure’ button next to your instance.

In the ‘Repositories’ panel, click ‘Add Repository’, and add any repositories you’d like to track commits from. The integration will then send Sentry metadata (such as authors and files changed) about each commit pushed to those repositories.

If you’re linking a GitHub repository, ensure you have Admin or Owner permissions on the repository, and that Sentry is an authorized GitHub app in your GitHub account settings.

If you’re still having trouble adding it, you can try to disconnect and then reconnect your GitHub identity.

Associate Commits with a Release

In your release process, add a step to create a release object in Sentry and associate it with commits from your linked repository.

There are 2 ways of doing this:

  1. Using Sentry’s Command Line Interface (recommended)
  2. Using the API
Using the CLI
# Assumes you're in a git repository
export SENTRY_AUTH_TOKEN=...
export SENTRY_ORG=my-org
VERSION=$(sentry-cli releases propose-version)

# Create a release
sentry-cli releases new -p project1 -p project2 $VERSION

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

In the above example, we’re using the propose-version sub-command to automatically determine a release ID. Then we’re creating a release tagged VERSION for the organization my-org for projects project1 and project2. Finally we’re using the --auto flag to automatically determine the repository name, and associate commits between the previous release’s commit and the current head commit with the release. If you have never associated commits before, we’ll use the latest 10 commits.

If you want more control over which commits to associate, or are unable to execute the command inside the repository, you can manually specify a repository and range:

sentry-cli releases set-commits --commit "my-repo@from..to" $VERSION

Here we are associating commits (or refs) between from and to with the current release, from being the previous release’s commit. The repository name my-repo should match the name you entered when linking the repo in the previous step, and is of the form owner-name/repo-name. The from commit is optional and we’ll use the previous release’s commit as the baseline if it is excluded.

For more information, see the CLI docs.

Using the API
# Create a new release
curl https://sentry.io/api/0/organizations/:organization_slug/releases/ \
  -X POST \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '
 {
 "version": "2da95dfb052f477380608d59d32b4ab9",
 "refs": [{
 "repository":"owner-name/repo-name",
 "commit":"2da95dfb052f477380608d59d32b4ab9",
 "previousCommit":"1e6223108647a7bfc040ef0ca5c92f68ff0dd993"
 }],
 "projects":["my-project","my-other-project"]
}
'

If you’d like to have more control over what order the commits appear in, you can send us a list of all commits. That might look like this:

import subprocess
import requests

SENTRY_API_TOKEN = <my_api_token>
sha_of_previous_release = <previous_sha>

log = subprocess.Popen([
    'git',
    '--no-pager',
    'log',
    '--no-merges',
    '--no-color',
    '--pretty=%H',
    '%s..HEAD' % (sha_of_previous_release,),
], stdout=subprocess.PIPE)

commits = log.stdout.read().strip().split('\n')

data = {
    'commits': [{'id': c, 'repository': 'my-repo-name'} for c in commits],
    'version': commits[0],
    'projects': ['my-project', 'my-other-project'],
}

res = requests.post(
    'https://sentry.io/api/0/organizations/my-org/releases/',
    json=data,
    headers={'Authorization': 'Bearer {}'.format(SENTRY_API_TOKEN)},
)

For more information, see the API reference.

After Associating Commits

After this step, suspect commits and suggested assignees will start appearing on the issue page. We determine these by tying together the commits in the release, files touched by those commits, files observed in the stack trace, authors of those files, and ownership rules.

Additionally, you will be able to resolve issues by including the issue ID in your commit message. You can find the issue id at the top of the issue details page, next to the assignee dropdown. For example, a commit message might look like this:

Prevent empty queries on users

Fixes SENTRY-317

When Sentry sees this commit, we’ll reference the commit in the issue, and when you create a release in Sentry we’ll mark the issue as resolved in that release.

Alternatively: Without a Repository Integration

If you don’t want Sentry to connect to your repository, or you’re using an unsupported repository provider or VCS (e.g. Perforce), you can alternatively tell Sentry about your raw commit metadata via the API using the create release endpoint.

Formatting Commit Metadata

In order for Sentry to use your commits, you must format your commits to match this form:

{
    "commits": [
        {
        "patch_set": [
            {"path": "path/to/added-file.html", "type": "A"}, 
            {"path": "path/to/modified-file.html", "type": "M"},
            {"path": "path/to/deleted-file.html", "type": "D"}
        ], 
        "repository": "owner-name/repo-name", 
        "author_name": "Author Name", 
        "author_email": "author_email@example.com", 
        "timestamp": "2018-09-20T11:50:22+03:00", 
        "message": "This is the commit message.", 
        "id": "8371445ab8a9facd271df17038ff295a48accae7"
        } 
    ]
}
patch_set

A list of the files that have been changed in the commit. Specifying the patch_set is necessary to power suspect commits and suggested assignees. It consists of two parts:

path
The path to the file. Note both forward and backward slashes ('/' '\\') are supported.
type
The types of changes that happend in that commit. The options are:
  • Add (A)
  • Modify (M)
  • Delete (D)
repository
The full name of the repository the commit belongs to. If this field is not given Sentry will generate a name in the form: u'organization-' (i.e. if the organization id is 123, then the generated repository name will be u'organization-123).
author_email
The commit author’s email is required to enable the suggested assignee feature.
author_name
The commit author’s name may also be included.
timestamp
The commit timestamp is used to sort the commits given. If a timestamp is not included, the commits will remain sorted in the order given.
message
The commit message.
id
The commit id.
Create the Release with Patch Data

Below is an example of a full request to the create release endpoint that includes commit metadata:

curl https://sentry.io/api/0/organizations/your-organization-name/releases/ \
  -X POST \
  -H 'Authorization: Bearer <Token>' \
  -H 'Content-Type: application/json' \
  -d '
 {
 "version": "2.0rc2",
 "projects":["project-1","project-2"],
 "commits":[
     {
        "patch_set": [
            {"path": "path/to/added-file.html", "type": "A"}, 
            {"path": "path/to/modified-file.html", "type": "M"},
            {"path": "path/to/deleted-file.html", "type": "D"}
        ], 
        "repository": "owner-name/repo-name", 
        "author_name": "Author Name", 
        "author_email": "author_email@example.com", 
        "timestamp": "2018-09-20T11:50:22+03:00", 
        "message": "This is the commit message.", 
        "id": "8371445ab8a9facd271df17038ff295a48accae7"
    }
 ]
 }
 '

For more information, see the API reference.

Tell Sentry When You Deploy a Release

Tell Sentry when you deploy a release and we’ll automatically send an email to Sentry users who have committed to the release that is being deployed.

You must have environment context set in your SDK in order to use this feature. To let Sentry know you’ve deployed, just send an additional request after creating a release:

sentry-cli releases deploys VERSION new -e ENVIRONMENT

You can also use our API to create a deploy.

Release Artifacts

JavaScript and iOS projects can utilize release artifacts to unminify or symbolicate error stack traces. To learn more, please check out our iOS and JavaScript docs.