Integrating Jira with GitHub

Organizing Source Code And Jira Board

Posted by Celinton Rayen on May 21, 2018

Most software development is successful only with collaborative effort (Developers, Product Manager/Owner, Business Stakeholders and the list grows). And so is the collaboration of the tools used in the process. Agree? Alright, I have seen teams start their sprint cycle on the kanban/scrum board with great energy and enthusiasm. Developers are sometimes too busy working on the complex stories/tasks, that they forget to switch the workflow status of the story on the board. On the last day of the sprint, magically the story would have been closed. Really? Also, in some instances, the developers commit their work in GitHub repo, move the story to DONE in the kanban board. What is the problem here? I foresee couple of challenges:

  1. The reports might not reflect the actual effort during the sprint.
  2. The story/task would have been marked as Done, though the VCS might not reflect the same. (As there is no link between GitHub and Jira) Let me take you through how Jira and GitHub together make our life simpler during the development process.

    Linking Jira with GitHub

    Jira connects to GitHub using OAuth. With that said, it is a simple two step process that makes this successful.

    Pre-requisite - Install the DVCS connector (if missing)

    For this, you should be an admin in Jira. If not, please approach a Jira admin. To install this,
      1. Click on the administrative settings in the toolbar.
      2. Choose add-ons.
      3. Search for DVCS connector and install.

1. Register OAuth application in GitHub.

    Open the account/org in GitHub which is the owner of the repository you
    want to link in Jira. (For this, you should be the owner of
    the account/team/org)
      1. Goto settings Tab.
      2. Click OAuth Applications.
      3. Click Register a new application.
      4. Provide the details.
      5. In the homepage URL and Autorization callback URL,
         enter your Jira homepage url.
      6. Once you click the Register application. This will generate a Client ID
         and Client Token. Keep this handy we will use it shortly.

Github OAuth Settings

2. Configure GitHub for Jira

  1. Login as an admin in Jira
  2. Click development tools
  3. Select GitHub/Enterprise (whatever your VCS is).
  4. In the Host URL section, enter your GitHub base url.
  4. Enter your team name.
  5. Provide the Client ID & Secret we generated in the earlier step.
  6. Make sure both Auto link and Enable smart commits are checked.
  7. Save the changes.

Jira OAuth Settings Page Now your account would start the sync up process. NOTE :

  • Make sure you create the OAuth client ID & secret under the account which owns the repository.
  • Step 6 in Configure GitHub for Jira is very important. Now the setup is complete. Let’s see how we can be smarter with smart commits. Smart commits are the secret to making life easier. Smart commits are none other than our regular commits with some smart tags. Whenever a developer commits his/her work, he/she logs the commit messages in a given format. For smart commits, listed below are few frequently used formats.
  • Create a branch in the repo with the story id prefixed.
    Format: <STORY-ID>Branch_name
    Example: PLAY-114_Create_User_Module
    where PLAY-114 is the story ID.
  • Committing the changes.
    Format: <STORY-ID> #<workflow-stage> #comment <Commit_message>
    Example: git -commit -m "PLAY-146 #in-progress #comment Test commit for Jira hooks"
    The above example would map the commit to PLAY-146, move the story
    to In Progress stage, and log a
    comment in the story Test commit for Jira hooks

    Commits File Changes summary in Jira

  • Creating pull requests.
    Once the pull request is created for the linked story, the details of the pull requests, should be available in Jira.
    NOTE: While creating the pull request, the smart commit #review would
     automatically switches the story to Review stage in Jira board.

    Pull request summary in Jira Pull request summary in Jira


    With the integration of two great tools, it saves a huge time and effort in tracking the product development. It also makes things organized. Happy Integrating!

posted on May 21, 2018 by
Celinton Rayen