This guide describes how to setup Swarmia for a self-hosted GitHub Enterprise Server instance
This guide was written using GitHub Enterprise version 3.1.1
The following steps are needed to get Swarmia installed in the GitHub Enterprise server:
- Create a new Github App
- Share secrets with Swarmia
- Add firewall rules
- Contact Swarmia to continue installing the app
1. Create Swarmia app
In your GitHub Enterprise organization settings, select GitHub Apps under Developer
Settings. Select New GitHub App.
Fill out the form with the following values:
GitHub App name: Swarmia
Homepage URL: https://www.swarmia.com
Identifying and authorizing users
Callback URL: https://app.swarmia.com/auth/github/callback/[your-github-organization-name]
Expire user authorization tokens: ✅
Request user authorization (OAuth) during installation: ✅
Webhook
Active: ✅
Webhook URL: https://hook.swarmia.com/GithubWebhook
Webhook secret: <random-string-with-high-entropy>
Enable SSL verification: ✅
Repository permissions
Checks: Read-only
Contents: Read-only
Deployments: Read-only
Issues: Read-only
Metadata: Read-only
Pull requests: Read & write
Projects: Read-only
Commit statuses: Read-only
Organization permissions
Members: Read-only
Projects: Read-only
Blocking users: Read-only
User permissions
Email addresses: Read-only
Subscribe to events
✅ Meta
✅ Check run
✅ Check suite
✅ Commit comment
✅ Create
✅ Delete
✅ Deployment
✅ Deployment status
Where can this GitHub App be installed?: Any account
Click Create Github App.
After you've created the app, you will see the below message.
Click generate a private key.
It will take you to the Private keys section. Click Generate a private key button.
swarmia.date.private-key.pem will be downloaded.
After successfully registering your application, you can optionally add a logo to your app. Here is a pre-cropped image you can use:
Make a note of your App ID, Client ID, and Client Secret. you will need those to connect your GitHub Enterprise Server with Swarmia in the next step. App ID and Client ID should be visible and client secret you can generate.
Finally, generate a Client secret, and store it somewhere safe. You'll need that in a bit:
2. Share your settings with Swarmia
💡 You should have acquired App ID, Client ID, Client Secret, Webhook secret and Private key in the previous steps. Share these secrets securely with this Google Form and let your Swarmia contact person know that you're done with this part of the setup.
If you're using a self-signed TLS certificate in your GitHub Enterprise instance please supply a TLS certificate pair to be used by Swarmia as a client certificate when contacting your GitHub Enterprise endpoints.
3. Configure your firewall
If your GitHub Enterprise is behind a firewall you’ll need to allow Swarmia's IP address so we can perform GitHub Enterprise API calls and receive webhooks.
- Inbound IPs (we make HTTPS requests to your GitHub instance): 34.89.165.89 & 35.234.103.84
- Outbound IPs (GitHub makes HTTPS requests to us): 34.117.202.112 (hook.swarmia.com) & 34.107.207.241 (app.swarmia.com)
4. Install the Swarmia app in organization(s)
After you've completed steps 1, 2, and 3 let Swarmia know you're ready to install the app. We then run the installation on our end, after which you're free to install the Swarmia app to your chosen organization(s). The app can be found at https://[hostname]/github-apps/swarmia where users can install it to their organization(s).
