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 to get started.
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
OrganizationPersonal
Start by following GitHub's official guide on 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 |
| Organization permissions / members (optional) | Read-only |
| Account permissions / Email addresses (optional) | Read-only |
| Repository / Actions | Read & write |
| Repository / Checks | Read & write |
| Repository / Code quality | Read-only |
| Repository / Code scanning alerts | Read-only |
| Repository / Commit Statuses | Read & write |
| Repository / Contents | Read & write |
| Repository / Issues | Read & write |
| Repository / Pull requests | Read & write |
| Repository / Webhooks | Read & write |
When prompted to subscribe to events, choose the following:
- Check run
- Check suite
- Delete
- Fork
- Issue comment
- Issues
- Member
- Membership
- Organization
- Public
- Pull Request
- Pull request review
- Pull request review comment
- Push
- Release
- Repository
- Status
- Team add
Trick
Enabling optional permissions will also enable the GitHub SSO for your instance.
You'll be given various credentials, configure them in config.yml:
Copied
# 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"
# 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:
Copied
github-app.private-key: |
-----BEGIN RSA PRIVATE KEY-----
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
-----END RSA PRIVATE KEY-----
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:
Copied
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-----
"""
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.