Table of contents

Purpose

GitHub is one of the most popular source code management provider.
In addition to source code management it offers a bugs and feature requests tracker, a task manager, continuous integration tools and a wiki.

Connecting Elements Connect fields to GitHub REST API allows you to:

1. Create a GitHub repository picker using /search/repositories endpoint
2. Create a User picker listing users existing of your GitHub organization using the /search/users endpoint
3. Reference and display details of a GitHub issue from a Jira issue using the /search/issues endpoint
4. etc...

The opportunities are numerous, you should have a look at the GitHub REST API documentation to discover more.

Configuration

We'll use the OAuth2 authorization code grant type to configure this datasource.

The configuration is done in two steps:

1. Register a new OAuth application from GitHub
2. Configure the GitHub datasource from Elements Connect

Those steps are described below.

Register a new OAuth application from GitHub

1. Create a new OAuth Application
2.  Settings:
   • Name: A meaningful name like "Elements Connect" or the name of your Jira instance. This value is not used by Elements Connect and will only be visible from GitHub.
   • Homepage URL: your Jira base URL or the homepage of Elements Connect. This value is not used by Elements Connect and will only be visible from GitHub.
   • Application description: Optional field, this value is not used by Elements Connect and will only be visible from GitHub.
   • Authorization callback URL: https://JIRABASEURL/nfeed/admin/models/datasources/oauth/_callback 
   • Click on Register application
3. You are redirected to your application home page on Github
4. Click on Generate a new client secret
5. Write down the Client ID and the Client Secret. 
   You'll need them to configure the datasource in Elements Connect.

That's it from the Github side.

 If you want to learn more about OAuth apps on GitHub, please have a look at the documentation provided by GitHub.

Configure the datasource from Elements Connect

Now, you'll create a new datasource in Elements Connect.
You must be a Jira admin.

• Login into Elements Connect administration
• Go to Datasources
• Add a new URL datasource

• Settings:
  • Name: Github (or any value that makes sense to you)
  • URL: https://api.github.com
  • Authentication: OAuth2
  • Content type: JSON
• Click on the Configure button below Authentication

• Settings:
  • ClientID: the Client ID obtained from Github at the previous step
  • Client secret: the Client secret obtained from Github at the previous step
  • Authorise URL: https://github.com/login/oauth/authorize 
  • Token URL: https://github.com/login/oauth/access_token 
  • Scopes: depends on your needs, check the documentation on Github about scopes
• Click on Get new credential
• You're redirected to Github authorization screen
• Click on the green Authorize XXX button
• You're redirected to the Elements Connect datasource configuration page
• The "The authorisation process was successful." message informs you that the configuration is successful 
• Click on Close
• You can save the datasource by clicking on the Save button

That's it 

You can now connect your fields to Github REST API.
See how to list GitHub repositories in an Elements Custom field.