GitHub Integration
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.
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 |
| 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 for your instance.
You'll be given various credentials, configure them in config.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:
github-app.private-key: |
-----BEGIN RSA PRIVATE KEY-----
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
privatekeyprivatekeyprivatekeyprivatekey
-----END RSA PRIVATE KEY-----
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").