# GitHub There are three types of GitHub integrations, so make sure you're choosing the correct one: * [GitHub](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#installing-github) - For individual GitHub users/organizations (as well as most GitHub Enterprise Cloud customers), so long as they are hosted on `github.com`. Follow the '[Installing GitHub](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#installing-github)' instructions, **Please begin the installation from Sentry**. * [GitHub Enterprise](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#installing-github-enterprise) - For GitHub Enterprise instances that **cannot be accessed from `github.com`**. Usually these will have a custom domain, for example: * `https://github.example.com` * `https://ghe.example.com/` For these accounts, follow the '[Installing GitHub Enterprise](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#installing-github-enterprise)' instructions. * [Seer GitHub App](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#installing-the-seer-github-app) - For [Seer](https://docs.sentry.io/product/ai-in-sentry/seer.md) to make Pull Requests for Issue Fixes and for [AI Code Review](https://docs.sentry.io/product/ai-in-sentry/ai-code-review.md) to analyze your Pull Requests. ### [Check Your Domain](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#check-your-domain) To determine which integration to use, enter your GitHub domain below: GitHub Domain https\://github.com or https\://ghe.example.com Sentry owner, manager, or admin permissions, and GitHub owner permissions are required to install this integration. ## [Installing GitHub](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#installing-github) 1. In Sentry, navigate to **Settings > Integrations > [GitHub](https://sentry.io/orgredirect/organizations/:orgslug/settings/integrations/github)**. 2. 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**. 3. In the resulting modal, click "Add Installation". 4. A GitHub install window should pop up. Click "Install". 5. Select which repositories Sentry should have access to (or select all repositories). 6. You should then be redirected back to the Sentry Integrations page. 7. On your new GitHub instance in Sentry, click "Configure". 8. 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.* 9. You can now [configure](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#configure) the integration. The GitHub integration is available for all projects under your Sentry organization. You can connect multiple GitHub organizations to one Sentry organization. Connecting a GitHub organisation to multiple Sentry organisations is supported on Sentry organisations on a Business or Enterprise plans (not supported for GitHub Enterprise Server). While you can install the GitHub integration from [GitHub](https://github.com/apps/sentry-io), we recommend installing it from Sentry for a more streamlined process. ### [GitHub Permissions](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#github-permissions) The following permissions are required for the GitHub integration to work correctly. You must fully opt in to these permissions to use the app. All permissions listed are repo-level permissions, unless otherwise indicated. | Permission Category | Access Level | Why Sentry Needs It | | ------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | Administration | Read-only | To respect branch protection rules, determine default branches, and enhance automation. | | Checks | Read & Write | To show detailed pass/fail results (e.g. test coverage, release health) as GitHub Checks on PRs or commits. | | Commit Statuses | Read & Write | To post status checks (e.g. test analytics data) to commits in GitHub and integrate with branch protection rules. | | Contents | Read-only | To fetch source files, commits, and blame data for Suspect Commits, tracking files in Releases. | | Issues | Read & Write | To create GitHub issues from Sentry events and update linked issues. | | Members **\[Org-level]** | Read-only | To map organization users to GitHub identities for improved issue attribution and collaboration. | | Metadata | Read-only | To identify repository structure, names, default branches, and visibility. | | Pull Requests | Read & Write | To write comments on pull requests for (1) issues caused by the pull request and (2) to highlight existing issues in the code diff. | | Webhooks | Read & Write | To subscribe to real-time updates like push events, PRs, and issues. | Occasionally, Sentry will request additional permissions to your GitHub account as new features are introduced. Denying or ignoring the request to update will not affect your current Sentry usage, but may prevent access to future features. ## [Installing GitHub Enterprise](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#installing-github-enterprise) ### [Add new GitHub App](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#add-new-github-app) 1. Confirm [Sentry's IP ranges](https://docs.sentry.io/security-legal-pii/security/ip-ranges.md) are allowed for your GitHub Enterprise instance. 2. 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](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#register-new-github-app) 1. First, you'll need to generate a webhook secret. For example, in terminal: ```bash openssl rand -base64 500 | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1 ``` 2. Then in GitHub, fill out the form as follows and click "Create GitHub App". | GitHub App Name | sentry-app | | ------------------------------- | --------------------------------------------------------- | | Homepage URL | | | User authorization callback URL | | | Setup URL | | | Webhook URL | | | 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 & Write | | Repository Contents | Read & Write | | 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](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#install-your-github-app) 1. In Sentry, navigate to Organization Settings > **Integrations**. 2. Next to GitHub Enterprise, click "Install". 3. Click "Add Installation". 4. Fill out the following form with information from your GitHub apps configuration page. The installation URL must be resolvable over the Internet. 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: ```bash cat | pbcopy ``` 5. 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". 6. You will then be redirected back to Sentry. On your new GitHub Enterprise instance, click "Configure". 7. 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. ## [Installing the Seer GitHub App](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#installing-the-seer-github-app) The [Seer GitHub App](https://github.com/apps/seer-by-sentry) is used by [Seer](https://docs.sentry.io/product/ai-in-sentry/seer.md) to make Pull Requests for Issue Fixes and for [AI Code Review](https://docs.sentry.io/product/ai-in-sentry/ai-code-review.md) to analyze your Pull Requests. To install the Seer GitHub App, simply follow the installation steps to install the GitHub App for the specified organization/repositories you need. You can find the Seer GitHub App [here](https://github.com/apps/seer-by-sentry). * For [Issue Fix](https://docs.sentry.io/product/ai-in-sentry/seer.md#issue-fix), you will now be able to create pull requests in the installed locations. * For [AI Code Review](https://docs.sentry.io/product/ai-in-sentry/ai-code-review.md), continue following the instructions in the [Sentry Prevent AI](https://docs.sentry.io/product/ai-in-sentry/sentry-prevent-ai.md#getting-started) documentation. ## [Configure](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#configure) Use GitHub to [track commits](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#commit-tracking), identify [suspect commits](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#suspect-commits-and-suggested-assignees), [resolve via commit or PR](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#resolve-via-commit-or-pull-request) and [manage issues](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#issue-management). ### [Commit Tracking](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#commit-tracking) Commit tracking allows you to hone in on problematic commits. Learn more about [commit tracking](https://docs.sentry.io/product/releases/setup/release-automation.md). ### [Suspect Commits and Suggested Assignees](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#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](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#issue-management) Issue tracking allows you to create GitHub issues from within Sentry, and link Sentry issues to existing GitHub Issues. ##### Note Manual issue management is available to organizations on Team, Business, or Enterprise plans. Automatic issue management is available to organizations on Business or Enterprise plans. Issue management can be configured in two ways - automatically or manually. #### [Automatically](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#automatically) To configure issue management automatically, create an [**Issue Alert**](https://docs.sentry.io/product/alerts-notifications/issue-alerts.md). When selecting the [**action**](https://docs.sentry.io/product/alerts/create-alerts/issue-alert-config.md#then-conditions-actions), choose **Create a new GitHub issue**. A GitHub issue will be created automatically when the alert has been triggered. #### [Manually](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#manually) To configure issue management manually, once you've navigated to a specific Sentry 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](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#resolve-via-commit-or-pull-request) Once you are sending commit data, you can start resolving issues by including `fixes ` in your commit messages. For example, a commit message might look like: ```bash Prevent empty queries on users Fixes MYAPP-317 ``` You can also resolve issues with pull requests by including `fixes ` 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 ` in the body of your pull request that is going to be merged to your main branch. ### [Get Sentry Comments on Pull Requests](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#get-sentry-comments-on-pull-requests) Sentry can comment on merged and open pull requests. These features are automatically enabled once your GitHub integration has been set up. To disable it, go to **Settings > Integrations > GitHub** and toggle it off. #### [Merged Pull Request Comments](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#merged-pull-request-comments) If a recently merged pull request is suspected of causing an issue, Sentry will comment on it to surface the issue, as shown 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. #### [Open Pull Request Comments](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#open-pull-request-comments) When a pull request is opened, Sentry will parse the filenames and function names modified in the pull request from the PR diff to find recent unhandled, unresolved issues associated with your pull request. Sentry will comment on the pull request with up to five issues per file that were first seen within the past 90 days and were last seen within the past 14 days. This feature requires [code mappings](https://docs.sentry.io/product/issues/suspect-commits.md#2-set-up-code-mappings) and is currently only supported for Python, JavaScript/TypeScript, PHP, and Ruby files. If you're using a different language, [let us know on this GitHub ticket](https://github.com/getsentry/sentry/issues/69824). For JavaScript/TypeScript, please ensure that you've unminified your code by [setting up source maps](https://docs.sentry.io/platforms/javascript/sourcemaps.md). ### [Missing Member Detection](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#missing-member-detection) If there are users committing to GitHub repositories linked to Sentry and they're not members of your organization, Sentry detects them as missing members. Once a month, Sentry sends organization owners and managers an email reminding them to invite those users to join their org. Sentry also shows a banner to invite missing members in the **Settings > Members** page. The banner shows the 5 most active contributors that are not yet in the organization. To see all missing members (up to 50), click "View All" in the banner. To snooze the banner, click the ellipsis, then select "Hide Missing Members". Clicking "View All" on the invite banner will display the invite modal. From here, you can select multiple users and assign roles and teams before inviting them. By default, this feature is automatically enabled once your GitHub integration has been set up. To disable it, go to **Settings > Integrations > GitHub** and toggle it off. ### [Stack Trace Linking](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#stack-trace-linking) Sentry will automatically try to set up code mappings on C#, Clojure, Go, Groovy, Java, JavaScript, PHP, Python, Ruby, and Scala for organizations with the GitHub integration installed. If your project uses a different SDK, you can add code mappings manually. 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**). 1. Navigate to **Settings > Integrations > GitHub > Configurations**. 2. Click the "Configure" button next to your GitHub Instance. 3. Click the **Code Mappings** tab. 4. Set up a code mapping for each project for which you want to enable stack trace linking. To create a new code mapping, click **Add Mapping**. 5. 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): See below for information on determining these values. #### [Stack Trace Root and Source Code Root](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#stack-trace-root-and-source-code-root) The following information is only valid for platforms which use traditional file paths. Platforms with package names require additional steps. For **Java**, read more in the [page on source context](https://docs.sentry.io/platforms/java/source-context.md#setting-up-code-mappings). First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`. For certain native platforms, the stack trace will look different. In cases like these, you can find the absolute path by hovering over the filename. If you aren't sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename` or `abs_path`. Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo). Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code. For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible. ### [Code Owners](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#code-owners) This feature is available only if your organization is on a [Business or Enterprise plan](https://sentry.io/pricing/). 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](https://docs.sentry.io/product/issues/ownership-rules.md#code-owners). ### [GitHub Single Sign-On](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#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](https://docs.sentry.io/organization/authentication/sso.md). ## [Troubleshooting](https://docs.sentry.io/organization/integrations/source-code-mgmt/github.md#troubleshooting) If you're having issues adding a GitHub repository: * Make sure you are the Owner of your GitHub organization. * [Disconnect](https://sentry.io/account/settings/identities/), and then [reconnect](https://sentry.io/account/settings/social/associate/github/) 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](https://docs.sentry.io/security-legal-pii/security/ip-ranges.md). * Sentry's access to your installation URL is not path restricted.