GitHub

The following instructions describe how to configure OAuth2 using GitHub.

Step 1: Register OAuth2 Provider in MergeBoard

To start the process of adding a new provider, click on the Add OAuth2 Provider button in MergeBoard.

../../_images/oauth2_add.png — Form to add a new OAuth2 provider.

Select the provider type GitHub from the list and enter a provider name (will be displayed to users in the login dialog). To proceed click on Next.

Step 2: Register OAuth2 Provider in GitHub

In GitHub you can create and register OAuth2 applications either under your personal account or under any organization you have admin access to.

In the following we will explain the steps for applications under your personal account, please refer to the GitHub documentation for more details.

Open github.com and click on the profile photo in the upper-right corner of the page. Then click on Settings.

../../_images/oauth2_github_001.png — GitHub dropdown menu after clicking on profile photo in the upper-right corner.

In the left sidebar, click on Developer settings and then on OAuth Apps. Click on New OAuth App to open the registration form.

../../_images/oauth2_github_002.png — Form to register a new OAuth2 application in GitHub.

Application name: The name of the application can be chosen freely. It will be displayed to users when they log in.
Homepage URL: The homepage URL can be chosen arbitrarily. We suggest to enter the URL to your MergeBoard workspace.
Application description: An arbitrary message that will be shown to users before they login. You can also keep this field empty.
Authorization callback URL: This must match the Redirect URL as shown in MergeBoard after completing the first form of the OAuth2 provider creation.
Enable Device Flow: MergeBoard currently does not use the device flow, so this can be kept unchecked.

After registering the application, click on Generate a new client secret. Save both the Client ID and Client Secret, those values will be needed to finish the configuration in MergeBoard.

Step 3: Complete Configuration in MergeBoard

Back in MergeBoard, fill out the form as follows.

Enable Provider: Enable the checkbox to allow users to login via this provider.
GitHub Server URL: Should be https://github.com for the public GitHub instance. When using a self-hosted GitHub instance, enter the address of your GitHub server.
GitHub API URL: Should be https://api.github.com for the public GitHub instance. When using a self-hosted GitHub instance, enter the address of your GitHub server.
Client ID: Enter the Client ID as shown by GitHub.
Client Secret: Enter the Client Secret as shown by GitHub.

Once you are happy with the settings click on Save.