Skip to content

GitHub Setup

Jump to bottom
Dave Bauman edited this page Mar 7, 2022 · 6 revisions

GitHub Setup

GitHub Service Account

Insights Explorer primarily interfaces with GitHub on behalf of the logged-in user, but there are some actions performed with a service account. The service account can be any user with admin permissions on the default org. This service account must be configured prior to running Insights Explorer.

The following tasks use the service account:

  • Syncing a repository to Insights Explorer
  • Automatically adding users to the default org
  • Querying information about users, repositories, collaborators

With the exception of adding users to the default org, these tasks all deal with reading data. Creating or editing Insights is always performed on behalf of a specific user.

The service account must be configured in two environment variables:

Creating the Service Account Access Token

  1. Login to GitHub as the user you want to act as the service account

  2. Go to the Settings / Developer settings / Personal access tokens page

  3. Click the Generate new token button

  4. Provide a note & set the expiration. If you select anything other than No expiration you will have to regenerate the token and update Insights Explorer when it expires.

  5. Select the following scopes:

    • repo
    • admin:org
    • read:user
    • user:email
    • admin:repo_hook

  6. Click Generate token at the bottom of the page

  7. Copy and paste the token into your Insights Explorer configuration.

GITHUB_SERVICE_ACCOUNT=username
GITHUB_ACCESS_TOKEN=ghp_************************************

Additional Information

If you ever need to come back and update the token scopes, you can update without regenerating the token. If you ever regenerate the token, you will need to update Insights Explorer and restart it.

GitHub Organization

Insights Explorer creates new Insights in a configured GitHub organization (GITHUB_DEFAULT_ORG). This org must be configured prior to running Insights Explorer; there is no default value.

If you already have a GitHub organization, you can connect Insights Explorer to it. Otherwise, you will need to create a new organization.

🎯 Tip: If you want to try out Insights Explorer, creating a new test organization will make it easier to clean up afterwards instead of using an existing org.

Creating an Organization in GitHub

The following process is written for GitHub.com, but is applicable for either GitHub.com or GitHub Enterprise Server, although the interface might look slightly different.

  1. Open GitHub.com and ensure you are logged in. In the top right, click on the + button and select New organization

Screen Shot 2022-03-07 at 9 50 04 AM

  1. Select a pricing plan for the new organization depending on your needs. Insights Explorer works with the free option.

  2. Fill out the organization form, including a unique name & contact email.

Screen Shot 2022-03-07 at 9 58 27 AM

  1. Once the organization is created, you can update the org profile, add additional users, etc.

  2. Finally, use the name of the org to configure the GITHUB_DEFAULT_ORG environment variable in Insights Explorer.

GITHUB_DEFAULT_ORG=insights-explorer-rocks

Additional Information

Two important points about permissions and your new Organization:

  1. In order to create a new Insight, a user must be a member of the org with permission to create new repositories. Insights Explorer uses the Personal Access Token of the logged in user to create repositories, rather than a service account.

  2. In order to edit an existing Insight, a user must have write permission to the repository. This permission can either be inherited from the org, or they can be added as an outside collaborator directly on a repository.

GitHub OAuth Application

OAuth2 is a protocol that lets external applications request authorization to private details in a user's GitHub account without accessing their password.

GitHub can be used as an OAuth provider for Insights Explorer. This means GitHub takes care of authenticating users, and securely passes that information back to Insights Explorer. IEX does not use this OAuth app to perform actions on behalf of the user; it only uses it to identify the user.

To configure this, a new GitHub OAuth app must be created. This app can be owned by a user or an organization. We recommend creating it on the default org used by Insights Explorer.

Creating a GitHub OAuth App

  1. Open the Organization settings and go to the Settings / Developer settings / OAuth Apps page

  2. Click the New OAuth App button

  3. Fill out the App form with meaningful values for name, homepage, and description.

  4. Set the Authorization Callback URL to auth/callback on your Insights Explorer instance:

    1. If you are planning run locally with Docker or Docker Compose, set it to http://localhost:3001/auth/callback
    2. If you are planning run locally from source (e.g. npm start), set it to http://localhost:3000/auth/callback
    3. If you have deployed Insights Explorer with a dedicated URL or IP address, set it accordingly with a path of auth/callback

  5. Create the App.

  6. Once created, you must generate a new client secret using the Generate new client secret button.

  7. Copy both the Client ID and Client Secret into your Insights Explorer configuration:

OAUTH_CLIENT_ID=***************
OAUTH_CLIENT_SECRET=*******************
Clone this wiki locally