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
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.
- 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.
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.
Do not forget trailing slashes for the URLs.
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,
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
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.
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.
Public link is the App URL and ID is App ID.
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.
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).
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)