I recently joined an established software development team in a large enterprise who exclusively used GitHub for issue tracking. From a developers perspective, it made sense. GitHub becomes your one-stop shop for tracking, version control and source code management.
If it ain’t broke, why fix it?
The Product Owner and I talked about backlog visibility and found this was one of the major challenges with the current setup. As the team maintains a number of services spread across multiple GitHub repositories, there was no single board to view and refine a combined backlog. Another challenge was that there were no estimations or story points, with more of a gut-feel approach on what could be completed in any given sprint.
After a few retros, we noticed some common themes occurring. So we decided to do an agile baseline health-check to further validate where we could improve. We individually scored our team on various agile fundamentals then had a big retro to review the results. Some of the common themes we struggled with were, in part, directly related to those limitations in our issue tracking mentioned earlier. Clarity on the product vision and backlog management was an issue, which a single backlog view could improve. Sustainable pace was an issue, which estimations and understanding our velocity could help with. The quality of user stories was also an opportunity for us to grow, which would require discipline — but perhaps the right tool could accelerate the process!
For the record, our target areas could be tackled in lots of ways! But for this article, we’ll focus on issue tracking and the backlog.
Out of the box, Github’s project board is essentially a kanban that can be setup quickly and easily. It has some automation available around tickets being moved between status columns which is handy, but it’s not really a backlog view. For a more traditional backlog, you could potentially view each repository’s issue list separately, but that wasn’t feasible for us with 15–20 repositories — imagine backlog refinement! 😱
The only way to combine all of them (in out of the box GitHub) is to use a project board.
Aside from not really being a traditional backlog offering, a limitation of the project board is that it is not suited to larger projects and teams with a higher number of issues. In those environments, you may not want to use automation to add all new issues to the board, or it will get cluttered quickly and lose clarity. Therefore, you’ll be adding cards manually using the Add Cards pane. This offers no drop-down menus or auto-fills for simplified searching, so if you’re running a lot of repositories and issues this becomes a bit daunting.
Another limitation of GitHub’s project boards is that a maximum of twenty-five repositories can be linked to one board. For most teams this isn’t a problem. However, it’s worth considering how your team and product might grow over time when making a choice.
Whilst I’m sure there are many ways to customise your GitHub, our team wanted a light-touch setup. Those who have worked in large enterprises will know the challenges in customising your operational tooling, with approvals and dependencies likely to slow down any significant change.
At least it’s super easy to get rolling with.
Alternatively, Jira could take slightly longer for that initial setup but may offer more value overall.
We decided to go with Jira for a few reasons, one of them being the backlog view. We added quick filters to allow the PO to switch between the combined backlog view of all issues or to view issues only for a particular service. While at the same time, developers could bookmark the Jira board with the quick filter(s) for their current workstream already selected — saving them from the noise of unrelated issues.
The backlog view in Jira allows us to drag and drop issues between sprints and backlog easily. We can drag priority tickets to the top of the backlog to visualise and plan how the next sprints will look, ensuring our refinement ceremonies are more meaningful.
Our team had identified two key problems relating to the contents of issues — a lack of estimations and user story quality being a little “lacking”. In GitHub, there’s no built-in field to capture effort. How could we plan for a sprint if we couldn’t quantify the required work in some way? Well, Jira not only had a built-in field to capture story points but also shows this against each issue in the backlog. It also displays totals above the active sprint of story points to do, in progress and done. Use of story points can be enhanced with some add-ons for burndown and velocity charts, which in our case were already available in our Jira environment. Within 3–4 sprints, we started getting some consistency and understanding the velocity we could achieve in each sprint on average. This has brought more confidence to our sprint planning and helps improve toward a sustainable pace for the team.
On the second problem of user story quality; as touched on earlier this would require discipline from the team, but could also be helped with by the right tool. By simply enabling the Acceptance Criteria field in our Stories in Jira and making it mandatory, we were reminding ourselves to meet some minimum requirements on all of our Stories. This was a basic example of prompting the user, but plenty of Jira’s built-in fields could be used to guide users in the right direction.
Another benefit with issue content was using Epics to group Story issue types. Where previously in GitHub, we were trying to loosely group related tasks using combinations of labels or milestones, the Epic issue type allowed us to create a high level parent issue with some information around the overall goal of that feature or enhancement. This is far superior to a GitHub label, for example, as it allows information such as acceptance criteria or a business-level user story, to be held at the top level Epic — as well as allowing the Epic itself to transition through a workflow.
Migrating from GitHub to Jira
Having decided as a team to give Jira a try, we started migrating GitHub tickets to Jira in increments. Fortunately, we were able to use GitHub’s API for this instead of writing out hundreds of issues manually. We used the list-repository-issues call (API docs / enterprise API docs) to extract all open issues in a particular repository, then used an open source tool to convert JSON to CSV, then tidied up the CSV into a format we could import into Jira.
A limitation is that the issue comments don’t come back in that API response; instead you’ll need to make a second API call for each issue to another endpoint for comments. As our comments were low volume and not worth the extra effort, we simplified the approach and instead made the CSV template a tiny bit fancy by concatenating the original GitHub issue link into the new Jira description to be imported. That way if anyone wanted to check the original link for comments it was right there in each Jira ticket.
When would GitHub work best for issue tracking? In my opinion, it could work in smaller development or support teams who only need a simple kanban setup and have a lower volume of issues. Perhaps it could also work for high-performing, well-established development teams with other methods and tools for estimations, reporting, backlog refinement and visualisation!
When would Jira work best for issue tracking? From my experience, when directly comparing to GitHub, Jira gets the chocolates in most categories. Especially in large enterprises where transparency and reporting are fundamental. Yes, it can take longer for initial setup depending on your requirements, such as for more complex workflows. However, if you need a lightweight setup there are built-in workflows.
One downside is that you need some customisation to link Jira issues directly to GitHub pull requests, which developers may bemoan when comparing to GitHub.
Hopefully this information helps as you consider the needs of your team. Good luck!
I have no affiliation with Jira or GitHub. I’m just a nerd for organisation.