Issue tracking on git platforms such as GitHub, GitLab, and Bitbucket plays a key role in managing features, bugs, and enhancements. They are a daily chore that most engineering and product managers are tasked with as a part of their jobs.
This post covers some of the most effective ways to manage repository issues that have helped our engineering team increase our velocity and ship features faster. Let’s dive in!
What is issue tracking on Git?
Issue tracking is a feature that resides in the projects tab in all three of the major git platforms. This feature integrates fully with the development lifecycle of repositories. When issue tracking is used on a git platform, it purely resides on the repository itself. Therefore the term git issue tracking.
Both open source and private repositories that wish to have a fully integrated way of managing issue tickets tend to use the built-in issue tracking features within GitHub, GitLab, and bitbucket. While they’re limited in functionality, they do allow managers to easily manage and plan work in a waterfall or semi-agile methodology.
For open source projects, git issues are the primary method of maintaining open source communities. Open source projects are the most frequent adopters of git issue tracking since they have to openly maintain issues and vulnerabilities in their code base. This allows project owners to easily track and display issue tickets that are tightly linked to pull requests on their repos.
How to track Git Issues using linking?
Most projects that have multiple project owners and stakeholders solemnly use git issue tracking as a primary way of managing and planning their work. Git platforms have very limited functionality in regards to tracking and planning work for teams that have product and engineering managers.
Most organizations that fall into this bracket tend to use more established platforms to manage their workflows. These organizations will mainly adopt issue tracking tools such as Jira, Shortcut or countless others.
Importing Git Issues
The method in which organizations work with issues on git, when an external issue tracker is involved is typically by linking or by importing. This creates a large divide in the visibility of work since every time issue tickets are created in git, they need to be constantly updated in the issue tracking platform.
1-1 Issue Ticket Linking
Another way that engineering and product teams offset the need for importing is by linking issue tickets in a 1-1 format. In this method, engineers create issue tickets on the git platform and then add the issue ID from Jira, shortcut, etc into the body or title of the git issue ticket with a hyperlink.
This usually results in ticket redundancy and miscommunication since engineers or product managers have to actively maintain copies of the same ticket in two systems, this also means that any updates to those tickets have to be done manually by copy pasting the data or by creating a custom API workflow.
Git Issue Syncing with Tara.ai
Seamlessly syncing issue tickets from your favorite git platform is a preferred method for most companies that follow an agile process. Engineers and managers who use the tara.ai platform are able to maintain a two-way sync between their GitHub issue tickets by using the official Tara AI github app.
This allows engineers and managers to maintain product visibility and better plan their work without directly affecting the stream of issue tickets on GitHub. Tara AI actively syncs ticket data from GitHub in real-time.
Any changes that engineers make on tickets title, description, status and label on GitHub will be directly shown in the Tara AI workdrawer. The same applies to changes made on Tara AI’s end. When a manager or engineer makes any changes to a git issue ticket on Tara, the changes are directly shown on GitHub.
Effective organization of your Git Issues
Git issues can get unwieldy over time. The longer a git issue stays open, the higher the likelihood that it’s going to either be ignored, left unplanned, or collect an immense number of status changes. In order to maintain a manageable stream of work, it’s important for engineering and product managers to frequently open, close, or hold issue tickets.
In the open source world, this management of issue tickets becomes even harder. Since any user of the repository is able to create issue tickets inside the repo, it becomes much harder to gate the tickets being created. This usually results in tickets that lack information, contain irrelevant issues or are duplicates of other open tickets.
In either case, whether you’re an open source repository or a closed project repo, it’s essential to maintain a readable backlog of work that directly aligns with your product roadmap. Below are some easy-to-follow methods of maintaining clear and concise workstreams for your git issue tickets.
Label your Git Issues
Labeling git issues is one of the easiest ways of managing your git issues. Some git platforms such as GitHub and GitLab provide default labels that can easily be applied to issue tickets. Labeling your ticket ensures that it’s easy to find and filter when you’re looking for specific tickets to work on.
💡 Tips: labeling your ticket as a #bug, #enhancement or #feature can help segment your tickets better. Adding secondary labels for version numbers and severity (such as sev1, sev2, sev3, etc) can also convey useful information to engineering teams when it comes to prioritizing work. They also provide a great way of visually identifying information at a glance.
Use Short and Concise Ticket Titles
We always come across folks that will attempt to put a full description into a git issue ticket title. While in practice it looks like it decreases the amount of work you need to do filling out a form, it in fact increases the time taken to manage the ticket by 2x.
Remember that ticket management in any git platform is cross functional. Any person reading the ticket should be able to read and understand it within 10 seconds. All supplementary information that relates to the ticket and steps to reproduce an error or even build a new feature should be housed in the ticket description.
💡 Tips: instead of writing “Fix bug found in task input box in registration page due to component unmount in version 3.6” your ticket can be structured like so: “Broken Task Input Box on Registration Page” and then add the labels “V3.6” and “Bug” and some more details on how to reproduce the bug within the description of the ticket. This will not only make the task easier to read but also make it searchable.
Organize your Tickets into Sprints
Organizing tickets by severity or milestones is usually not ample enough to release and deliver software on time. In order to really drive alignment and transparency across your engineering and product teams, it’s important to timebox git issue tickets into sprints.
The advantage of taking your git issue tickets and organizing them into sprints is that it allows you to have better clarity around what new features, bugs, and enhancements are being shipped. It also allows the team to remain on the same page when it comes to short-term and long-term product roadmap goals.
We suggest using Tara AI’s GitHub app and our git issue sync feature to seamlessly plan and organize your tickets into sprints. This allows the wider team to easily visualize the work week over week without changing any of the workflow that is pre-set inside GitHub.
Lastly, it also lets engineering managers, product owners, and stakeholders visualize tickets in an easy-to-understand format on the Tara AI progress view. The timeline view takes git issue tickets and lets you track progress per requirement and per engineer, making it effortless to see when and how engineers are shipping code.
Weekly Issue Ticket Clean Up
A once-a-week ritual of cleaning up issue tickets by a person delegated on the team can also ensure that duplicates and redundant work is not cluttering your planning activities. We recommend setting up a recurring calendar invite and assigning one person a week from your engineering or product team to clear up tickets that are:
- Blocked (issue tickets that can’t progress due to some dependency on a person or subsequent work)
- Not Doing (issue tickets that are out of scope, too ambitious or outside current team capabilities)
- Duplicates (issue tickets that are similar to others in your backlog that may have been opened by other team members)
- Stale (issue tickets that are over 3 months old that are open but do not correlate with your current objectives or roadmap)
You can easily use the guidelines in the bullet points above for closing tickets that match the criteria or create your own guidelines. Over time the weekly clean-ups become a habit and your team will become more accustomed to doing it on their own.
Linking Pull Requests to Issue Tickets
Linking your incoming pull requests is another effective strategy to identify whether tickets are being worked on. Whilst pull request statuses are different from issue ticket statuses, they are correlated.
In the open source world, internal linking of git issues to pull requests is very common. It has been the de facto way for repo owners to convey crucial information to their communities about security patches and product updates.
Linking a Pull Request to a git issue ticket usually implies that code for that ticket has been pushed and is ready to review. Most organizations using issue-tracking apps outside of GitHub, GitLab, and Bitbucket commonly use this method to track work. Within Git platforms the concept of internal reference PRs is a great way of communicating to the team how far along the code is.
Teams can also use the Tara AI platform to easily automate their issue ticket linking by simply adding their task ID to the branch. This in turn tracks the full lifecycle of the git issue ticket in more depth and also ensures that its status is autonomously updated when the code is merged into a certain environment.
Saving Time by syncing Git Workflows in Tara AI
Effectively managing git issue tickets can take countless hours in a week but some of the tools and techniques that are mentioned in our post can help bring more control to the chaos. A mix of both software tooling outlined processes and creating healthy issue ticket management habits can create better alignment around software delivery objectives.
In addition to that, using tools such as Tara AI and Git together can help drive focus on product goals and bring more visibility into product delivery. Automating the manual work of git issue ticket updates and syncing data back and forth between systems becomes a less of worry when planning and organizing your work on the platform.