# GitHub Integration

## [Create a GitHub App](https://docs.sentry.io/.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.

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

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.md).

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 / 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://docs.sentry.io/self-hosted/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-----
```
