Setup Github integration

With release v.2.8.23 we introduced the option to publish tickets directly to Github. In the past it has been possible to publish to TFS or Jira, but since we at TrustSource left Jira already quiet a while, we felt that we urgently required the Github integration. And here we are:

A simple approach follows these three steps:

1. To allow Github integration, you will first setup a Github access token.
2. Place the token in the corporate or project settings.
3. Link the repo
4. Start pushing issues

The following sections will address each of the steps in detail and add some thoughts. We recommend to read through the text first (requires maybe 10 mins) and then decide how to proceed based on the gained understanding.

1. Create a Github Access Token

PLEASE NOTE: At the time of writing, the fine gained access tokes were still under beta at Github. In case some changes occur or another, favourable mechanism will occur, we might adjust this article.

TrustSource allows to setup one general access token on corporate level. or project specific tokens on project level. Given there is a project level token defined, it will overwrite the global token. To generally allow github integration, we recommend to setup a global token and add project specific users, where required.

As of now, the user creating the token must be in the owner's role for the organisation. If he is just a member, it seems that he will not be allowed to create tokens for all the repositories. Thus we recommend to create a special Github user in the owner role for the organisation and limit his rights, so that he will not be able to do more than read and write issues.    

PLEASE NOTE: All tickets will carry the name of the account associated with the token owner!

However, with the user you want to create such a token, go to the Github organization of interest and select "Settings" and scroll down to jump into "Developer Settings". There choose "Personal access tokens" and pick the "Fine-grained tokens". It is written that the feature still is in beta. But we expect it to become GA in a few weeks without much of change.

Here you use the button on the right to generate a new token. In the next dialogue assign a name, e.g. TrustSourceIssueAccess. It should be a name that allows you to understand its purpose. You will not need the name but it will be listed under this name and therefor help, what the token is used for. 

The define an expiration date. Default is 30 days. You might need to verify this with you security policies. We recommend to pick a custom date, e.g. 90 days an define a reminder to renew the key accordingly. An additional description might be useful as well.

In the next selector you should seek the resource owner. This selection determines scope of addressable repositories. Only repositories owned by the resource owner will be addressable with the key. This scope can further be limited in the following section. You also may use the selector of specific repositories to verify whether the required repos are included.  

Now it is time to select the permissions granted. If you select "Repository permissions", you may choose the rights you want to grant the key owner. TrustSource will require "Read & write" Access to the Issues only! This will automatically add "read-only" access to Metadata. That's it. 

You now may return and trigger the generation of the key. PLEASE NOTE: This will be the only time you will be able to see the key. Use the built in copy-function and store it immediately to TrustSource.

THERE IS NO PROBLEM WITH LOOSING THE KEY. YOU JUST GENERATE A NEW ONE AND REPLACE IT IN TRUSTSOURCE.  

2. Place the token into TrustSource

If you have an ACCOUNT-ADMIN role, you may set the global token. To set the project specific token, a PROJECT MANAGER  role is sufficient. 

For the global token select ADMINISTRATION > INTEGRATIONS and there choose the GITHUB ISSUES INTEGRATION. Given you have a Corporate or Enterprise subscription, you will be able to enter the key here. If you do not have a suitable subscription, a message will inform you about the situation.

PLEASE REMIND to also activate the checkbox below the key and press the update button. This will apply your access token. 

To enter it on project level, go to PROJECTS > YOURPROJECTNAME and select SETTINGS. In the tab ISSUE INTEGRATION you may select the type of integration and define corresponding access credentials:

3. Link to Repository

Finally you need to provide the repo-link in the corresponding module settings. Therefore switch to the settings of the module and on the general tab add the repository link:

And that's it. From now you may start publishing issues.

4. Publish issues

Go to any finding, e..g in the details view, select the task icon  and see the status. It may either offer to create an issue or show you the status of it. Clicking in the "create" will allow you to edit the issue message, clicking on e.g., "open" will let you jump directly into the repo issue on Github.