JIRA workflow automation using GitHub web hooks

‘Hey! Why is that JIRA still in To-do if you are already working on it?’, ‘Why is that JIRA still In Progress if the changes are already in QA?’, ‘Hey, can you make sure everyone in the team is updating the JIRA status properly?’ How many of us have come across situations like these at our workplaces? Every techie would have certainly heard this thousands of times in his career. This in fact could be one of the biggest reasons for altercations between a boss and his subordinate. While it’s natural for a developer to forget updating the status of a JIRA when he’s fully engrossed in his work, it also sounds like a petty issue to him. But for a manager, to track the progress of his team, having the JIRA board updated is vital. So, how do we solve this conundrum?

Obviously by reducing the manual intervention and automating the transitions. Not only can the developer concentrate on pushing his work to QA and not worry about setting the status of the JIRA every time, the manager can also be extremely confident of the status of the JIRAs on the board. Yes, we tried the same and it worked wonders for us. The developers have reached a stage where they have even forgotten the credentials of JIRA(It could be partly because of SSO as well ;-))

How did we reach there?

As mentioned in the title, we used GitHub web hooks to achieve this automation. We initially tried to use the work flow triggers on the JIRA by connecting to GitHub. Although this could handle some simple transitions, it provided limited options for customizing the transitions. So we set out to find a better alternative. We knew we could easily play around with JIRAs using the REST APIs. But when do we invoke was a big question. That is when my manager suggested the smart commits feature on the JIRA. The name initially made us wonder if the JIRA would smartly do the transitions based on the transactions on GitHub on its own, but later we realized that some one had to explicitly invoke the smart commit commands to make the transitions. When we continued exploring further, we stumbled across the option of GitHub web hooks. Although we had configured the web hooks for Jenkins integration before, creating a web hook from scratch on our own seemed like a big deal to start with.

What are these web hooks?

For those who do not know what web hooks are, web hooks are simple endpoints that keep listening to events published by GitHub and do necessary processing on the JSON included in the event payload. Since there were not many articles or blogs on internet on how to get started with writing web hooks, we struggled a bit to get the basic web hook in place. GitHub certainly had some documentation on how to configure web hooks, however, it didn’t help us in understanding how to create one. Then we began to wonder if it was just about having an endpoint(public URL specified on web hook configuration) listen to events, why not create a nodejs server hosted in a public domain and make it listen to these events. Well, our guess seemed to work like a charm. Since we had the scripts running locally on our system, we had to use a proxy server to route the events to our locally hosted nodejs server(steps mentioned in GitHub documentation). And there we had our web hook displaying the JSONs published by the GitHub events.

How do they handle JIRA transitions?

The web hook which is a nodejs server, has to be hosted in a public URL (we hosted it on AWS cloud). The moment any activity occurs on GitHub, an event is raised by GitHub with relevant JSON in the payload. One could choose what events he wants to listen to on GitHub during the web hook configuration. On the server, we decipher the kind of activity that occurred on GitHub and invoke JIRA REST APIs to change the status of the JIRAs accordingly.

What we can do better?

We are planning to do more improvements to the current implementation going forward, which I would be sharing in the days to come once we bring them to fruition. Below are the areas we want to improve on :

• We need to explore how can we leverage on smart commit feature of JIRAS in place of JIRA REST APIs.
• We need to check how can we handle the transition of JIRAs in bulk.
• We need to explore the option of marking the release version on all the JIRAS after the release.

More details on the step by step procedure on how we achieved it can be found here. It even provides a link to the GitHub repository.

So far it has been working well with no issues. In fact, the whole implementation is so simple to encounter any issues. This is just a small step towards our goal of automating every inefficient and error prone manual steps we do in our day to day work. I hope this article will come handy to someone who shares the same goal as we do.