Create GitHub App

GitHub application forms the bridge between ReviewNB and GitHub. It enables user authentication via Oauth2 & let user select repositories that ReviewNB should have access to.

In this section, we’ll create a GitHub app for your self hosted ReviewNB installation. At the end, we require following fields to:

  • App ID
  • App URL
  • Client ID
  • Client secret
  • Private Key

Note

Throughout this document when we say GitHub account, it can be an individual/org account on github.com or your own GitHub enterprise installation, depending on the GitHub offering you are using.

Prerequisite

  • You need to decide the endpoint at which you’ll be running ReviewNB. It’s typically reviewnb.<your-domain-name>.com. Your application won’t be running there as yet but you just need to know the endpoint you’ll be using.

Create New App

Any GitHub account can own the app but we recommend creating it under org account of the team who is going to maintain the ReviewNB installation.

  • Login to GitHub & go to your org account page (e.g. https://github.corp.company.com/tools-org).
  • Click on Settings -> GitHub Apps -> New GitHub App as shown below.
../_images/gh_app_1.png

Setup URLs and Genral Information

Fill in the general information as shown in the screenshot. For URLs, replace reviewnb.<your-domain-name>.com with actual endpoint at which you’ll be hosting ReviewNB application.

Note

Do not forget trailing slashes for the URLs.

../_images/gh_app_2_v2.png

Setup Permissions

We need following permissions for enabling all the ReviewNB functionality,

  • Read repository contents to fetch notebooks and compute diff
  • Read repository metadata to fetch list of commits and PRs
  • Read-Write access to pull requests to read & write PR comments
  • Read access to emails for user profiles (Optional, older GitHub Enterprise do not have email permission)

You need to enable these under permissions section as shown below,

../_images/gh_app_3.1.png ../_images/gh_app_3.2_v2.png ../_images/gh_app_3.3.png ../_images/gh_app_3.4.png

Webhook Events & Scope

  • Subscribe to Pull Request events so ReviewNB is notified when a PR is created and it can post the ReviewNB link on the PR discussion.
  • For the question, “Where can this GitHub App be installed?” choose “Any account” so other orgs in your company can use ReviewNB as well. For on-prem installations that work with github.com, only repositories under your company’s org account can be accessed via ReviewNB.

Click on Create GitHub App

../_images/gh_app_4_v2.png

Generate Private Key

Once the app is created you can scroll down and click Generate private key. This will create and download a .pem file for you. Please keep this safe.

../_images/gh_app_5_v2.png

Get App Config

On your newly created app page, you can find Client ID, Client Secret, App ID, and App URL. Please note down these fields along with the private key generated in the above step. We’ll need to plug them as environment vaiables on the docker container.

../_images/gh_app_6.1.png

Public link is the App URL and ID is App ID.

../_images/gh_app_6.2.png

How to read Private Key

The private key you generated above would be downloaded as a .pem file. You need to open the .pem in any text editor and replace the newlines with \n. I demonstrate this with Sublime Text below. Notice the regex replacement I’m using at the bottom. If your editor doesn’t support it, you can manually replace newlines with \n.

../_images/before_replacement.png

After replacement, it should become a single line (as shown below) with \n between each of the previous line. If you’re replacing by hand, notice there’s a \n at the end of last line as well. This entire single line will be your Private Key (GITHUB_APP_PEM).

../_images/after_replacement.png

Summary

At the end of this section you should have following values to be used as environment variables for ReviewNB container.

  • App ID (GITHUB_APP_ID)
  • App URL (GITHUB_APP_URL)
  • Client ID (GITHUB_CLIENT_ID)
  • Private Key (GITHUB_APP_PEM)
  • Client secret (GITHUB_CLIENT_SECRET)