Installing GitHub Insights

Prerequisites

• You must have a GitHub Enterprise license file that includes GitHub Insights. After you purchase GitHub Insights, you can download the updated license file in the GitHub Enterprise web portal.

• GitHub Insights requires a machine, called the application server, hosted either in the cloud or locally. For more information, see "System overview for GitHub Insights."

• You must install dependencies on the application server.

  • Docker 1.13.0+
  • Docker Compose v1.17.0+
  • netcat, available via apt for Debian and Ubuntu

  Note: The application server may require the Docker daemon to be run as sudo. Kubernetes is not supported.

Creating a GitHub App

To connect GitHub Insights to GitHub Enterprise, you must create a GitHub App in an organization on GitHub Enterprise. A slugged version of your app's name will be shown on GitHub Enterprise when your integration takes an action.

1. Sign in to your GitHub Enterprise Server instance at http(s)://HOSTNAME/login.

2. Navigate to the organization you'd like to connect to GitHub Insights.

3. Under your organization name, click Settings.

   

4. In the left sidebar, click GitHub Apps.

5. Click New GitHub App.

6. Under "GitHub App name", type a name for the app. Your app cannot have the same name as an existing user or organization, unless the name is your own user or organization name.

7. Under "Homepage URL", type the URL of the application server for GitHub Insights. For more information, see "System overview for GitHub Insights."

8. Under "User authorization callback URL", type the following, replacing <application-server-url> with the URL of the application server.

   <application-server-url>/public/applogin
   

   

9. Under "Setup URL", type <application-server-url>/public/setup.

10. Under "Webhook URL", type <application-server-url>/webhooks.

11. Under "Webhook secret", type a secret, then record the secret for later reference.

12. Under "Permissions", use the drop-down menus and configure the following permissions for the app.

    • Repository:
      • Contents: Read-only
      • Metadata: Read-only
      • Pull requests: Read-only
      • Commit statuses: Read-only
    • Organization:
      • Members: Read-only
      • Projects: Read-only

    

13. Under "Subscribe to events", select:

    • Member
    • Pull request
    • Push
    • Repository
    • Team

14. To enable the GitHub App to access data from any user or organization in your GitHub Enterprise Server instance, under "Where can this GitHub App be installed?", select Any account.

15. Click Create GitHub App.

16. Review your app's configuration.

17. Under "Private keys", click Generate a private key.

18. Save the resulting PEM file for later reference.

19. Make note of the following information about your app for later reference.

    • App ID
    • Client ID
    • Client secret
    • Private key
    • Webhook secret

Installing GitHub Insights

1. From the application server, navigate to the latest release of GitHub Insights on the Releases page for github/insights-releases.
2. To download the latest release, under "Assets", click insights-VERSION.tar.gz.
3. Unzip the directory.
4. Run the shell script install.sh.
5. To enable SSL, enter the SSL Cert (.crt/.cer/.pem). If you don't want to enable SSL, leave blank.
6. If you chose to enable SSL, enter the SSL Key (.key). Otherwise, leave blank.
7. Enter the hostname, which is the same URL you used for the application server when creating the GitHub App.
8. The installation will take a few minutes to run. When complete, you will see a message printed to the terminal.

   Installation complete
   Run /opt/insights/scripts/start.sh to start GitHub Insights
   

9. To start GitHub Insights, run the shell script /opt/insights/scripts/start.sh.
10. If this is the first time starting GitHub Insights the script will take a few minutes to run. When complete, you will see a message printed to the terminal.

    GitHub Insights is running!
    

Configuring GitHub Insights

To configure GitHub Insights to connect to GitHub Enterprise Server, you must provide the information you recorded in previous steps.

1. In your browser, navigate to <application-server-url>/setup.
2. Under "GitHub API URL", type the URL you use to access GitHub Enterprise Server.
3. Under "GitHub Insights License", click "Choose Files", then upload your GitHub Enterprise license file.
4. Under "App ID", type the App ID of your GitHub App, which you recorded when creating the app.
5. Under "Client ID", type the client ID of your GitHub App, which you recorded when creating the app.
6. Under "Client Secret", type the client secret of your GitHub App, which you recorded when creating the app.
7. Under "Private Key", type in the private key of your GitHub App, which is contained in the PEM file you downloaded while creating the app.
8. Under "Webhook Secret", type the webhook secret of your GitHub App, which you recorded when creating the app.
9. If you did not provide a SSL certificate during installation, select Skip SSL Certificate Check.
10. Click Submit.
11. Click Log in with GitHub.
12. To authorize the GitHub App and access GitHub Insights, click Authorize GitHub App.

Further reading

• "Managing repositories"
• "GitHub Insights and data protection for your organization"