Feature availability


Feature

Freshdesk plans

GitHub plans

Link Freshdesk tickets with GitHub issues

All plans

Free, Micro, Small, Medium, Large


Feature Details

The GitHub app for Freshdesk allows you to link your tickets to new or existing issues in a GitHub repository of your choice. You can set milestones for these issues, track and resolve them as necessary. Any replies or notes that are recorded in your tickets will be added as comments in the linked GitHub issue and any comments are made in your GitHub issues will be reflected in the relevant Freshdesk ticket details page. 

Installation Procedure

  1. Sign into your helpdesk. Click on Admin → Apps → Get More Apps

  2. Select GitHub and click on Install.

  3. This will take you to GitHub’s authorization screen.

  4. Login to your GitHub account.

  5. Select the Organizations you want to allow Freshdesk access to and click on “Grant Access”. You will have to enter your password.


  6. Once access has been granted, click on “Authorize Application” to link your GitHub account to your helpdesk.

Please make sure that the you are the Owner of these linked repositories. It is possible to sync comments and notes between tickets and issues only if you have Owner access to the included repositories. For the repositories added without Owner privileges, any comments added to GitHub issues will not be updated in the corresponding Freshdesk ticket. 


Once you’ve linked your GitHub and Freshdesk accounts, the GitHub app Configuration page will be available to you. The following options are available:

  1. Select the possible subset of repositories that you want agents to have access to.

  2. If required, select the option that enables automatic mapping of Freshdesk ticket types to GitHub issue labels.

  3. If required, select the option that allows agents to assign milestones to GitHub issues.

  4. If required, select the status you want to associate with the linked Freshdesk ticket once a GitHub issue has been closed.

  5. If required, select if you want Freshdesk ticket responses and comments in GitHub issues to sync with each other.

NOTE: You can add up to 20 repositories.


Disabling and Re-enabling the app:
If you wish to disable the app, you can go to Admin → Apps and click on the button next to GitHub to disable it.

However, this will not de-authorize the Freshdesk app from GitHub. So if you re-enable the app from Freshdesk,, then your account will be automatically associated with the same GitHub organizations that you had linked earlier. If you want to completely sever all ties between the two accounts, follow these steps

Steps to unlink your GitHub profile from the Freshdesk App

  1. Go to your GitHub account. Click on your profile → Settings

  2. Under Personal Settings, select Applications

  3. Click on the Revoke button against Freshdesk


Steps to unlink your GitHub organizations from the Freshdesk App

  1. Under Organization Settings, click on the Organization that you associated with Freshdesk.

  2. Click on Third-Party Access and enter your password.

  3. Under “Third-Party application access policy”, click Revoke next to Freshdesk

  4. Repeat steps 1 to 3 for all organizations that you want to dissociate from Freshdesk.


Using The Feature

Once the app has been set up, agents can make use of the GitHub app widget in the sidebar on the ticket details page to associate a ticket with a new or existing GitHub issue.

If agents want to create a new issue, they:

  1. Need to select the appropriate repository from the admin-approved list

  2. Can select an available milestone and link it, based on admin configuration

  3. Can have ticket status type applied automatically as GitHub issue label, based on admin configuration. If the ticket status does not exist as a GitHub issue label, a new label will be created and applied.

  4. Can change the subject, which, by default, is same as that of the ticket.


The corresponding GitHub issue will contain the following details


A private note will also be added to the Freshdesk ticket



Linking a Ticket and an Issue:

If an agent wants to link to an existing issue, they will have to select the appropriate repository and enter the issue ID


A note will also be added to the Freshdesk ticket


You can link multiple tickets to same issue as well. However, any changes made to the status and comments section of that issue will be reflected only in the first Freshdesk ticket that was associated with that issue. For all other tickets, the app widget will provide the Freshdesk ticket ID where the changes can be tracked. Agents, if they so choose, may use the “Watcher” feature on Freshdesk tickets to get auto notifications regarding changes made.


Unlinking a Ticket and an Issue:
You can unlink the Freshdesk tickets from their GitHub issues at any time. Once you’ve unlinked a ticket, the following note will be visible on GitHub:



A corresponding note will also be added to the Freshdesk ticket:


In case of a multi-ticket link, if you unlink the Freshdesk ticket where the changes are being tracked, then the next ticket in the link order will automatically begin reflecting updates in the GitHub issue. The app widgets for other tickets in the multi-ticket chain will point to the new ticket to track these updates.


Types of Responses, Links, and Attachments - How they are handled


Responses: 

Every time you respond to a ticket, a comment is added to the linked GitHub issue. The comment will automatically include a one-line description of who the author of the comment is in Freshdesk, and the actual content of the comment. If you Reply, Forward or Add Note to a ticket, a comment will be added correspondingly. Any images that are present in your response will be included in the GitHub comment too.


Ticket notes converted to GitHub issue comments will be shown as being created by the user whose credentials were used to install the app. However, the first few lines of the comment will clearly specify which agent in your helpdesk authored the comment. Please note that the Freshdesk Admin should have enabled the “Add a comment in the GitHub issue, when a response is added in Freshdesk” feature in the app configuration page for this to work.

Any comments made in a GitHub issue linked to a ticket will be automatically added as a private note to that corresponding ticket. If the person adding the note is not an agent, then they will be added as a contact in your helpdesk. Please make sure that you have enabled the “Add a private note in the Freshdesk ticket, when a comment is added in GitHub” feature in the app configuration page for this to work. If your GitHub comment includes any images, it will be included in the note added to the Freshdesk.  


Links and Attachments: 

Irrespective of where you share files from - be it cloud storage solutions or locally - if a Freshdesk ticket has a file attached to it when converting to a comment, a link to the file will be included in the text of the comment. If you merely included a link in the description of your Freshdesk note, it will be accessible from GitHub as well. 


FAQ

  1. No repositories are being listed in the app configuration page. Why?
    For repositories to be visible in the app configuration page, the following criteria must be met:

    1. The GitHub app for Freshdesk must be granted access to the organizations containing the requisite repositories while setting up the app. Merely clicking “Authorize” after logging into your GitHub account will not suffice. If you did not grant access to any organizations while setting up the app, you will have to revoke permission from GitHub for the Freshdesk app and try linking again.

    2. The required repositories should be contained by those organizations that were associated with the app as mentioned in the previous point.

    3. Only Private Repositories can be used with this app. This is done to protect the content of Freshdesk tickets.

  2. Can I add a repository even if I am not its owner? What will happen?
    The User, whose GitHub credentials are used to authorize the Freshdesk-GitHub app, must be the owner of all repositories which are to be added in the app configuration page. This will allow all of the app features, such as bi-directional comment sync, to work as designed. In case the user is not the owner of one of the repositories, GitHub comments made for issues under that particular repository will not reflect in Freshdesk. Any ticket updates made in Freshdesk will still reflect in GitHub. 

  3. Do I have to set this up for every agent?
    No. This is an admin level app and as such will be available to all agents once you’ve set it up. 

  4. Tickets from Freshdesk and comments from GitHub aren’t syncing. Why?
    Please make sure your Admin has selected both options in the “Comment Sync” section in the app configuration page. 



  5. Can I delete a link between an issue and a ticket? Can I relink a ticket to a different issue?
    Yes. You can do this from the app widget. You may use this feature to relink a ticket to a different issue. A private note will be added every time a link is deleted or a ticket relinked to an issue.

  6. I followed the delink steps given in this article and uninstalled the app. Now, when I am trying to re-enable it, I’m not able to link one of the organizations. I get this "Red" icon. Why?


    If you revoked access to a particular repository from the Organization Settings page in GitHub, you can grant access only from there again.