GitHub
Track and resolve bugs faster by using data from your GitHub commits, and streamline your triaging process by creating a GitHub issue directly from Sentry.
Install
Sentry owner, manager, or admin permissions, and GitHub owner permissions are required to install this integration.
Navigate to Settings > Integrations > GitHub.
If you have the legacy GitHub integration installed, use the button next to GitHub to Upgrade. If you don't have the legacy GitHub integration installed, use the button to Install.
In the resulting modal, click "Add Installation".
A GitHub install window should pop up. Click "Install".
Select which repositories Sentry should have access to (or select all repositories).
You should then be redirected back to the Sentry Integrations page.
On your new GitHub instance in Sentry, click "Configure".
All of your repositories will be added by default, you just have to refresh your screen. To only add select repositories, choose them from the dropdown list. Make sure you have given Sentry access to these repositories in GitHub in the previous steps.
The GitHub integration is available for all projects under your Sentry organization. You can connect multiple GitHub organizations to one Sentry organization, but you cannot connect a single GitHub organization to multiple Sentry organizations.
GitHub Enterprise
Add new GitHub App
Confirm Sentry's IP ranges are allowed for your GitHub Enterprise instance.
In your GitHub Enterprise organization, navigate to Settings > Developer Settings > GitHub Apps and click to add a new New GitHub App.
Register new GitHub App
First, you'll need to generate a webhook secret. For example, in terminal:
Copiedopenssl rand -base64 500 | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1
Then in GitHub, fill out the form as follows and click "Create GitHub App".
GitHub App Name sentry-app Homepage URL https://sentry.io User authorization callback URL https://sentry.io/extensions/github-enterprise/setup/ Setup URL https://sentry.io/extensions/github-enterprise/setup/ Webhook URL https://sentry.io/extensions/github-enterprise/webhook/ Webhook secret `Input your secret from the previous step` Repository Administration Read-only Commit Statuses No Access Deployments No Access Issues Read & Write Pages No Access Pull Requests Read-only Repository Contents Read-only Single File No Access Repository Projects No Access Organization members Read-only Organization projects No Access Subscribe to Events
Pull Request Yes Push Yes
Install your GitHub App
In Sentry, navigate to Organization Settings > Integrations.
Next to GitHub Enterprise, click "Install".
Click "Add Installation".
Fill out the following form with information from your GitHub apps configuration page.
You'll need to generate a private key on your GitHub apps configuration page, and paste the entire contents into the GitHub App Private Key field.
For example, in terminal:
Copiedcat <YOUR_PRIVATE_KEY_FILE> | pbcopy
Click "Configure" and then a GitHub install window will pop up. Select which repositories Sentry should have access to (or select all repositories) and click "Install".
You will then be redirected back to Sentry. On your new GitHub Enterprise instance, click "Configure".
Add any repositories that you want to collect commit data from. Make sure you have given Sentry access to these repositories in GitHub in the previous steps.
GitHub Enterprise should now be enabled for all projects under your Sentry organization.
Configure
Use GitHub to track commits, identify suspect commits, resolve via commit or PR and manage issues.
Commit Tracking
Commit tracking allows you to hone in on problematic commits. Learn more about commit tracking.
Suspect Commits and Suggested Assignees
Once you set up commit tracking, you’ll be able to see the most recent changes to files found in the issue’s stack trace with suspect commits.
For issues where the files in the stack trace match files included in commits sent to Sentry, you’ll see the suspect commit, with a link to the commit itself.
You’ll also see that the author of the suspect commit will be listed as a suggested assignee for this issue. To assign the issue to the suggested assignee, click on their icon.
Issue Management
Issue tracking allows you to create GitHub issues from within Sentry, and link Sentry issues to existing GitHub Issues.
Once you’ve navigated to a specific issue, you’ll find the Linked Issues section on the right hand panel. Here, you’ll be able to create or link GitHub issues.
Resolve via Commit or Pull Request
Once you are sending commit data, you can start resolving issues by including fixes <SENTRY-SHORT-ID>
in your commit messages. For example, a commit message might look like:
Prevent empty queries on users
Fixes MYAPP-317
You can also resolve issues with pull requests by including fixes <SENTRY-SHORT-ID>
in the title or description.
When Sentry sees this, we’ll automatically annotate the matching issue with a reference to the commit or pull request, and, later, when that commit or pull request is part of a release, we’ll mark the issue as resolved. The commit must be associated with a release. Otherwise, if the commit is squashed, Sentry won’t know when the commit has been released, and the issue may never be marked as a regression. With GitHub, we recommend using fixes <SENTRY-SHORT-ID>
in the body of your pull request that is going to be merged to your main branch.
Get Sentry Comments on Suspect Pull Requests
If a recently merged pull request is suspected of causing an issue, Sentry will comment on it as in the example below.
Sentry will only comment on pull requests less than two weeks old that are associated with suspect commits. The comment will continuously be updated with up to five issues the pull request is suspected to have caused.
This feature will be automatically enabled for you once your GitHub integration has been set up. To disable it, go to Settings > Integrations > GitHub and toggle it off.
Stack Trace Linking
This feature is currently only supported for Ruby, Python, Php, Node, JavaScript, Go and Elixir.
Sentry will automatically try to set up code mappings on Python and JavaScript projects for organizations with the GitHub integration installed. However, you can still manually add code mappings if you choose to do so. Support for other languages and other source code integrations are planned.
Stack trace linking takes you from a file in your Sentry stack trace to that same file in your source code. If you have commit tracking set up in Sentry, we can take you to the exact version (using the commit associated with the event) of the source code when the error occurred. Otherwise we'll link you to the current state of the source code (using the default branch).
Navigate to Settings > Integrations > GitHub > Configurations.
Click the "Configure" button next to your GitHub Instance.
Click the Code Mappings tab.
Set up a code mapping for each
projectRepresents your service in Sentry and allows you to scope events to a distinct application.for which you want to enable stack trace linking. To create a new code mapping, click Add Mapping.Fill out the form, then click Save Changes. Each form field is described below:
project (required): This is the Sentry project.
repo (required): This is the GitHub repository associated with the Sentry project above. If you have more than one GitHub repository being used per Sentry project, you'll need multiple code mappings.
branch (required): This is the default branch of your code we fall back to if you do not have commit tracking set up.
stack trace root and source code root (optional):
If the file path in your Sentry stack trace frame matches the path to your source code, you do not need to set these values.
- ex. For example, everything after the branch (
main
) matches the file path ofcode.py
using a source code path ofhttps://github.com/MeredithAnya/testing/blob/main/code.py
so you don't need to set a stack trace root and source code root.
- ex. For example, everything after the branch (
If the filename in your Sentry stack trace frame doesn't match the path to your source code, you will need to replace the stack_root part of the filename with your source_root to make the filename match the source code path.
- ex. For example, to get
src/code.py
to matchcode.py
when the source code path ishttps://github.com/MeredithAnya/testing/blob/main/code.py
, change the stack trace root to be set assrc/
, and leave source code root empty.
- ex. For example, to get
Code Owners
This feature is available only if your organization is on a Business or Enterprise plan.
Import your existing GitHub CODEOWNERS files to automatically assign Sentry issues and route alerts to the responsible individuals and teams.
For more details, see the full documentation for Code Owners.
GitHub Single Sign-On
Single sign-on (or SSO) allows you to manage your organization’s entire membership via a third-party provider.
For more details, see the full documentation for Single Sign-on.
Troubleshooting
If you’re having issues adding a GitHub repository:
- Make sure you are the Owner of your GitHub organization.
- Disconnect, and then reconnect your GitHub Identity.
If you're having trouble setting up Sentry with your on-premises integration, verify the following:
- The provided installation URL is a fully qualified domain name (FQDN), which is resolvable on the internet.
- The IP addresses Sentry uses to make outbound requests are allowed.
- Sentry's access to your installation URL is not path restricted.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").