Associate Commits
Learn how to associate commits with a release.
This feature is only applicable for error issues. Other categories of issues (such as performance issues) do not support this feature.
In your release process, you can add a step to create a release in Sentry and associate it with commits from your linked repository. When you've done this, you'll be able to see the commits associated with a release in the Release Details page.
If you're using one of our release automation options, this step should be done automatically.
However, if you don't have a repository integration installed, you can send Sentry your raw commit metadata using the Sentry CLI or our API.
When you've associated commits, we can tie together the commits in the release, including:
- Files touched by those commits
- Files observed in the stack trace
- Authors of those files
- Issues resolved by those commits
In this CLI example:
- Environment variables configure the CLI (see Working with Projects for alternatives)
- The
propose-version
sub-command determines a release ID automatically - A release tagged
VERSION
is created for the organizationmy-org
for projectsproject1
andproject2
- Because of the
--auto
flag, the repository name is determined automatically, and commits between the previous release’s head commit and the current head commit are associated with the release.
# Assumes you're in a git repository
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
export SENTRY_ORG=example-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
If you don't have a repo-based integration associated with your Sentry organization, then the --auto
flag will automatically use the git tree of your local repo, and associate commits between the previous release's head commit and the current head commit with the release. If this is the first release, Sentry will use the latest 10 - 20 commits, depending on the integration. This behavior is configurable with the --initial-depth
flag.
Alternatively, you can use the --local
flag to enable this behavior by default:
sentry-cli releases set-commits --local $VERSION
For more control over which commits to associate, or if you're unable to execute the command inside the repository, you can manually specify a repository and range.
The following example associates commits (or refs) between from
and to
with the current release, where from
is the previous release’s commit. The from
commit is optional; we’ll use the previous release’s commit as the baseline if it is excluded:
sentry-cli releases set-commits --commit "my-repo@from..to" $VERSION
The repository name my-repo
should match the name you entered when linking the repo, and should be in the form owner-name/repo-name
.
To send Sentry your commit metadata using the API, use the create release endpoint.
Use the following format for your commits:
{
"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. Both forward and backward slashes ('/' '\\'
) are supported.
type
: The types of changes that happened 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-<organization_id>'
(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.
Here is an example of a request using patch data:
Confirm you’re using Auth Tokens, not API Keys, which are deprecated.
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"
}
]
}
'
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.
If you receive an "Unable to Fetch Commits" email, take a look at our help center article.
Additionally, when you've started associating commits with a release, you'll 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.
A commit message might look like this, for example:
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. You can also resolve issues with pull requests by including fixes <SENTRY-SHORT-ID>
in the title or description.
If you’re using GitHub, you may have a privacy setting enabled that prevents Sentry from identifying the user’s actual email address. To use the suggested owners feature, uncheck “Keep my email address private” in GitHub’s account settings.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").