๐Ÿ”Œ[WIP] Setting up 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.

2. Configure the oAuth App

On this screen, you need to fill three fields:

Then you can click register.

3. Create OAuth credentials for your appยถ

From this screen:

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:

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:

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):

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:

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:

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.

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:

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.

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!!

Last updated