Setting up GitHub Integration

Updated 3 hours ago by RSpace Support

Aim of this document

This section explains how, as an RSpace admin, you can set up RSpace to enable users to browse and import code snippets from GitHub into RSpace documents.

You don't need to do this if your RSpace web address has .researchspace.com domain. RSpace is supplied with default clientId and clientSecret. This work is only necessary if you prefer to create your own GitHub RSpace app for your users.

This is a one-off step - it does not need to be done for every RSpace user!

Pre-requisites

• An account on GitHub
• An organization on GitHub
  • The account used on GitHub must have Admin rights on the organization.
• Access to RSpace server in order to set in clientIds and secret you will acquire from GitHub
• The RSpace server must allow 2-way HTTPS communication with GitHub

Setting up the app on GitHub

1. Go to your organization, click on the Settings tab, then Developer Settings -> OAuth Apps.
   1. If you are setting up the application on a user, Click on your profile picture on the top right, then click on Settings.
2. Click on the New OAuth app button.
3. Fill in the form with the following information:
   1. Application Name: This will be displayed to your users. For example: RSpace GitHub Integration
   2. Homepage URL: This will be displayed to your users. We recommend using your RSpace instance URL.
   3. Application description: This is optional, and can be left blank.
   4. Authorization callback URL: this must be in the form of https://<RSpace Instance URL>/app/github/redirect_uri (e.g. https://myresearchspace.com/app/github/redirect_uri)
   5. Enable Device Flow: Leave unchecked.
4. Click Register Application.
5. You will then be taken to the OAuth App's settings page. Under Client Secrets, click on Generate a new client secret.
6. Note both the Client ID and Client Secret displayed on the page.

Steps in RSpace

1. Connect to the RSpace server using ssh, or Putty, or your preferred client
2. Open /etc/rspace/deployment.properties
   and add the following properties:
   github.client.id=<the client ID from GitHub>
github.secret=<the client secret from GitHub>
3. Save the file and restart RSpace
4. Log into RSpace, go to System -> Configuration -> System Settings, then set github.available to Allowed.

Testing the App

1. Logon to RSpace web application as an RSpace user and open Apps page. The GitHub integration should be listed under Disabled integrations.
2. Click on the GitHub card, then click Enable.
3. Click Add. This should take you through the GitHub authentication flow.
4. You should now be able to link GitHub repositories to your RSpace account.

How did we do?

Related Articles

• Introduction to configuring RSpace Apps
• Deploying RSpace
• Changelog