How to setup and create a Github Connector

Overview

The Github connector relies on the OAuth protocol for authentication Oauth is an industry-standard protocol for authorization. It allows a client to easily authenticate and authorize access to resources. You may not be familiar with the term, but you actually run through the OAuth protocol when you login to some of your apps and authorize access to your data via this kind of popup:

In Toucan Toco, as an administrator you can easily setup OAuth credentials for your platform. Once setup, any App Builder on your platform will be able to create a connection to Github in just a couple of clicks!

In this tutorial we will provide a step-by-step guide to help administrators get the required OAuth credentials and use them in Toucan Toco. Then we will show you how easy it is for an App Builder to create a Github connection in a Toucan application.

For Admins: How to get Github Oauth credentials

You will first need to go in the Github Developers Settings. From there, you will need to go through the following steps:

1. Create a new oAuth App

If you don’t have a Github application yet, or if you need to create a new application dedicated to your Toucan usage, you will need to create such an application and fill the required information.

Github settings Create a new app

2. Configure the oAuth App

On this screen, you need to fill three fields:

• Name, the application Name
• Homepage URL, the url of your Toucan Toco instance such as https://api-company.toucantoco.com
• Authorization callback URL, the URL called by Github for confirmation in your instance such as https://api-company.toucantoco.com/oauth/redirect?type=Github

Github settings configure App

Then you can click register.

3. Create OAuth credentials for your app

From this screen:

Github Settings Generate Credentials

Copy the client id. Click “Generate a new client secret” and copy the client secret

For Admins: How to add Github credentials on the platform

AS an admin, you can easily add Github credentials that will be available for all the apps of your platform.

From the apps store, click on the “””Admin area” button, and then click on the “Connectors” button:

Connectors button

You will land on a interface listing connectors for which you can add credentials. When no credentials have been filled for a given connector, the status will appear as “Not configured”, in red. To set new OAuth credentials for Github, click on the configure button:

Connectors Platform Interface

Now you can enter the client ID and client secret that you got by following the steps in the previous section (note that we show you in the popup the exact URL to copy-paste in the “Authorized URI” field of the Github App configuration):

Github oAuth Config

You are all set! You can save the form and you will now be able to get the OAuth credentials (client ID and client secret) that will be required in the Toucan Toco configuration.

For App Builders: How to create a Github connection in an application

Now from an application, if can easily create a Github connector:

Create Github connector

You will walk through a popup as shown at the very top of this tutorial page, where you need to first login and then authorize access to your Github. Please note, that you’ll need your Github organization’s admin to approve the application to be able to extract teams & pull requests data.

From there you can give a name to your connector:

Github connector configuration

Once you have checked that your connection works (click on “Test connection”), then you can save your connector. It will appear in your connectors list. To add a new dataset extracted from Github, click on “Add a query”:

You’re almost there… You just need to give a name to your datasource.

Github datasource configuration

From there, extraction will be done from the first organization your Github Account belongs to. Other available organizations will be displayed in the Organization dropdown list.

By default, the “teams” dataset will be retrieved (as it’s usually a small dataset). You can change the dataset to “pull requests” and it will retrieve a pull requests dataset:

Github datasource Datasets configuration

You can also configure the maximum number of pages to retrieve for the two datasets. Repositories & teams will be retrieved in full, but the pull requests won’t because of the potentially large number of pages to get from Github’s API.

Github datasource page_limit

Datasets explanation

The “teams” dataset is a membership dataset with a Github user as key and a list of teams which he belongs to as value. The “pull requests” dataset contains a list of extracted pull requests from all organization’s repositories with the repository name as key and values such as pull request title, creation date, merging date, author, etc…

That’s it! now if you save, your new dataset will be available in your application! Wonderful no ?

Have fun with your Github data!!