The GitHub connector for Elimity Insights fetches users, roles, teams, permissions and repositories from GitHub so you can keep in control of your environment. 

Follow the instructions below to set up the connector for your environment.

How it works

• Elimity Insights periodically fetches users, roles, teams, permissions and repositories from GitHub
• Write Elimity Insights queries to review and monitor updates to the data, or leverage existing queries.
• Configure these stored queries to take action when the Elimity Insights data changes.

Integration requirements

Setting up a GitHub source in Elimity Insights requires:

• an organization admin account in GitHub to create a GitHub App,
• a user in Elimity Insights with the role Connector Admin or higher.

Integration instructions

Follow the following steps to set up a GitHub source in Elimity Insights:

1. To ensure Elimity Insights can request the necessary information from the GitHub API, we need to provide it with a private key. GitHub only generates these keys for GitHub Apps, so we need to create a GitHub App first. To do so, paste the following link in your browser (filling the {organization} parameter) and log in with the organization administrator account:
   
   https://github.com/organizations/{organization}/settings/apps/new?administration=read&members=read
   
   Use 'Elimity Insights for {organization}' as the GitHub App name and the URL of your Elimity Insights installation as the homepage (these settings are purely descriptive). Untick the active checkbox under the webhooks section, and click the confirmation button.
   
   
2. Having created a GitHub App, now we can generate a private key for it. Clicking the confirmation button in the first step should have brought you to the new app’s settings page. At the top of this page you will find the app id, copy this value to the ‘App ID’ field in Elimity Insights. Scroll down to the private keys section, and click the button to generate a private key, which should download a file to your machine. Keep this file for the last step.
   
   
3. Elimity Insights will only be able to use the private key you just generated if the GitHub App is effectively installed for your organization. From the app’s settings page (where you should still be after the second step), click the button to install the app, which should be in the top-left menu. Click the install button for the organization account. Review the requested permissions and click the confirmation button.
   
   
4. Having created and installed a GitHub App, we can now effectively set up the import process. In Elimity Insights upload the private key you generated in the second step. Click the confirmation button and review the import status.

Troubleshooting

Failed parsing app id

The value for the ‘App ID’ field does not have the correct format. Make sure it is a numeric value.

Failed looking up app installations

The provided ‘App ID’ or ‘Private key’ is invalid, or the GitHub App has not been installed for your organization.

Could not refresh installation id xyz’s token

The GitHub App’s installation for your organization has probably been suspended. Check the GitHub App’s installation status on GitHub.

Changelog

v3.35.0

• The connector now also imports custom property values for each repository.

v3.36.0

• Permission entities now have an explicit 'type' attribute.