Installation instructions for self-hosted GitHub Enterprise Server

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:

  1. Create a new Github App
  2. Share secrets with Swarmia
  3. Add firewall rules
  4. 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.

Organizations_Umbrella-Corporation_settings_appsFill out the form with the following values:

GitHub App name: Swarmia

Homepage URL: https://www.swarmia.com

GHES2-Organizations_Umbrella-Corporation_settings_apps_new

Identifying and authorizing users

Callback URL: https://app.swarmia.com/auth/github/callback

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: ✅

GHES3_Organizations_Umbrella-Corporation_settings_apps_new

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

GHES4_organizations_Umbrella-Corporation_settings_apps_new

Organization permissions

Members: Read-only

Projects: Read-only

Blocking users: Read-only

GHES5_Organizations_Umbrella-Corporation_settings_apps_newUser permissions

Email addresses: Read-only

GHES6_Organizations_Umbrella-Corporation_settings_apps_newSubscribe to events

✅ Meta

✅ Check run

✅ Check suite

✅ Commit comment

✅ Create

Delete

Deployment

✅ Deployment status

✅ Issue comment
✅ Issues
✅ Label
✅ Membership
✅ Organization
✅ Project
✅ Project card
✅ Project column
✅ Pull request
✅ Pull request review
✅ Pull request review comment
✅ Push
✅ Team
GHES7_Organizations_Umbrella-Corporation_settings_apps_newWhere can this GitHub App be installed?: Any account

GHES8_Organizations_Umbrella-Corporation_settings_apps_newClick Create Github App.
After you've created the app, you will see the below message.

GHES9Click 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.

GHES10After successfully registering your application, you can optionally add a logo to your app. Here is a pre-cropped image you can use:

swarmia-logo-for-ghes

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:

GHES11

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 your Swarmia contact person. Also, share the URL you use to access GitHub Enterprise and if you have a public proxy for your GitHub Enterprise API share it as well.

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: 34.89.165.89 & 35.234.103.84
  • Outbound IPs: 34.117.202.112 & 34.107.207.241

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

GHES12_Organizations_Umbrella-Corporation_settings_apps_swarmia-test_installations