---
title: "GitHub"
url: https://develop.sentry.dev/integrations/github/
---

# GitHub Integration

## [Configure ngrok](https://develop.sentry.dev/integrations/github.md#configure-ngrok)

`ngrok` allows your local developer environment to be reachable by Github callbacks and webhooks and is needed for the `${url-prefix}` later on in this setup.

Follow the steps in the [ngrok documentation](https://develop.sentry.dev/development-infrastructure/ngrok.md) to get started.

## [Create a GitHub App](https://develop.sentry.dev/integrations/github.md#create-a-github-app)

To configure the GitHub integration you'll need to create a GitHub app and obtain credentials. Installation will fail if your GitHub App's name contains spaces.

For local development make sure to use your ngrok URL as the prefix.

The GitHub App name and GitHub Org Slug must not contain any spaces.

Account Type

\[x]Organization\[ ]Personal

GitHub Org Slug

your-organization

Sentry `url-prefix`

https\://your-sentry-url-prefix.com

Start by following GitHub's [official guide on creating a GitHub App](https://developer.github.com/apps/building-github-apps/creating-a-github-app/).

If the form above does not work for you, you need the following settings for your GitHub Application. You'll need to come up with your own webhook secret:

| Setting              | Value                                                                  |
| -------------------- | ---------------------------------------------------------------------- |
| Homepage URL         | `${url-prefix}`                                                        |
| Callback URLs        | `${url-prefix}/auth/sso/` and `${url-prefix}/extensions/github/setup/` |
| Setup URL (optional) | `${url-prefix}/extensions/github/setup/`                               |
| Webhook URL          | `${url-prefix}/extensions/github/webhook/`                             |
| Webhook secret       | "my-super-secret-example-secret"                                       |

When prompted for permissions, choose the following:

| Permission                                       | Setting      |
| ------------------------------------------------ | ------------ |
| Repository / Administration                      | Read-only    |
| Repository / Contents                            | Read-only    |
| Organization permissions / members (optional)    | Read-only    |
| Account permissions / Email addresses (optional) | Read-only    |
| Repository / Checks                              | Read & write |
| Repository / Commit Statuses                     | Read & write |
| Repository / Issues                              | Read & write |
| Repository / Pull requests                       | Read & write |
| Repository / Webhooks                            | Read & write |

When prompted to subscribe to events, choose the following:

* Pull Request
* Push

##### Trick

Enabling optional permissions will also enable the<!-- --> <!-- -->[GitHub SSO](https://develop.sentry.dev/self-hosted/configuration/sso.md#github-auth) for your instance.

You'll be given various credentials, configure them in `config.yml`:

```yml
# App ID
github-app.id: GITHUB_APP_ID
# App Name
github-app.name: "GITHUB_APP_NAME"
# Client ID
github-app.client-id: "GITHUB_CLIENT_ID"
# Client Secret
github-app.client-secret: "GITHUB_CLIENT_SECRET"
# Webhook Secret
github-app.webhook-secret: "my-super-secret-example-secret"
```

##### Invalid Application Name

If you're receiving invalid application or application not found error, it's suggested to change the `github-app.name` to the correct application slug. This can occur if the application includes non-alphanumeric characters.

Last, generate and download the private key, and add it to your configuration for your app:

```yml
github-app.private-key: |
  -----BEGIN RSA PRIVATE KEY-----
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  -----END RSA PRIVATE KEY-----
```

You can also use a `sentry.conf.py` file to store your configuration as follows:

```python
from sentry.conf.server import SENTRY_OPTIONS

# App ID
SENTRY_OPTIONS["github-app.id"] = GITHUB_APP_ID
# App Name
SENTRY_OPTIONS["github-app.name"] = GITHUB_APP_NAME
# Client ID
SENTRY_OPTIONS["github-app.client-id"] = GITHUB_CLIENT_ID
# Client Secret
SENTRY_OPTIONS["github-app.client-secret"] = GITHUB_CLIENT_SECRET
# Webhook Secret
SENTRY_OPTIONS["github-app.webhook-secret"] = GITHUB_WEBHOOK_SECRET

SENTRY_OPTIONS[
    "github-app.private-key"
] = """
-----BEGIN RSA PRIVATE KEY-----
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
-----END RSA PRIVATE KEY-----
"""
```

Take note that your private key should be a multiline string without any whitespace before the start of a new line of the key.