Getting the Most out of Github Issues |

For the longest time, I ran my own git server. I got a github account when I decided I wanted to start sharing code publicly. Then when I got serious about a startup, it just seemed like the obvious choice to host the code for our product since our team is spread out (San Antonio, Chicago, and Warsaw).

GitHub has a lot of features beyond just simple repository hosting. The social aspect of being able to not only fork, but use that as a means of a communication is really powerful. I’ll admit that much like I think better of an application that ships a deb, a project on github makes me more comfortable mixing it in to my tool kit.

The tool that took me the longest to the hang of is the Issue tracking system built into github. It is a little slow (given how much work they’ve done on the Wiki feature I’m hoping this is going to get some love), but other than that it is really pretty awesome.


If you are going to use the Issues tracker, you need to make sure that everything you do fits with its purpose.

The purpose of Issues is to provide a single place to store possible development work, and to manage what work is going to be done.

That gets broken down into two parts. The first is as a single place to store possible development work. When I originally started working with github, I used the wiki a lot more than Issues. The Wiki just seemed friendlier to the format and creation of stories. We would pick work from there and then use it to track everything. There is a distinct possibility that you could make that work, but what inevitably happened was that as soon as we started working on a story it got transfered to a issue. That just made it a heck of a lot easier to track the workflow on the story. Over time, I stopped putting stories in the wiki at all, and just went straight to Issues.

Even though it should be the single place for storing possible work, it does not mean it is the only place you should take feedback. At TruckingOffice, we use Zendesk to deal with customer issues. One each customer ticket that gets submitted, it gets triaged. If the problem they are having needs to be solved by code changes, then a new issue is opened in github.

I’ve experimented in the past with allowing tickets to flow directly from customers to developers. Unless your customers are developers, it just ends up in a really messy communication flow since through no fault of their own – customers rarely capture everything you need to know if their first submission, and for really bad issues you get a lot of duplicate submissions. The goal is to put issues into github in a form that allows a developer to take action on the problem. In the case of a story, you need to give a full statement. In the case of a bug, that means some guidance on how you detect it and if possible how you replicate it.

There are also a couple of practical issues with having customers put tickets into github. They need a github account, which if they already have one says something about what kind of person they are. If your repository is private, then I believe you would have to add them to the project which is going to be expensive and unwieldy unless you only have a couple of customers.

The point of all of this is, you can use lots of different tools to gather what ideas about what needs to be done. The most important thing is to make sure it all gets into the issue system. Maybe it was because I love lists, or because I spent so much time at Rackspace, but my first question once an issue gets brought up is – “did you start a ticket for this?”. Get in the habit of opening issues. It is much much easier to close an issue if it exists than if it is just something you talked about at a meeting.


Now that you have all of you work in one place, you get to the second key of using Issues – manging what you are working on. If you are like me, you start with just dumping issues into the system. You start by just working on the first in first out (or more likely last in first out). Once you get enough issues, you start messing with priority and trying to keep the stuff you want to look at at the top. After you cannot keep up with that, you might finally glance over at the right hand side and notice a thing called “Labels” which is just a way of tagging your issues.

Now I’ll admit that the label system is not perfect. For example you can filter the open list down by only one tag at a time, but there are some easy ways to work around that problem.

Here is how I setup my labels. I’ve included a list of my standards as well as my color code. You can always add or subtract to the list. You can also choose different colors. I recommend you use colors because it makes it much easier to get a sense about the issue you are looking at. Github allows you to tag an issue with multiple tags. Make use of that. Because of the issues with sorting, it is really really essential that you tag an issue with all the tags that apply to make sure it will show up in the list as you sort it different ways.

  • Bug: Color: red. This should be the most obvious category. This issue is about something that is broken.
  • Deploy: Color: bright blue. In small teams, one or more of the devs usually gets stuck with the deployment job (or more accurately when I’m on a small team I get stuck with it as well as development). Keeping track of deployment issues in the same place as everything else makes release planning a lot easier. It also smooths things out if a deployment issue needs dev work.
  • Feature/Story: Color:black . You can use either term. On official projects I tend to use the term story because I tend to be more disciplined about actually writing stories (As an X I want to Y so that I can Z). On my personal projects, tends to get a little more free form. Any time you see something in the issue that means you are making an improvement add this tag. It will help you write your change log later for your customers.
  • I-1 or I-n: Color: white,grey, bright green. Color depends on the stage. They are default grey when created. If they are completed I make them white. If one of them is active I make it bright green. The I stands for Iteration. I use a number once it is actually in use. I use an n as a place holder. I have bastardized the term iteration in this usage. Basically, I use these tags to collect up issues that follow a theme. For example – user authentication or integrating with google. When it comes time to schedule work, I can actually choose a bundle of issues that are thematically related. Or in some cases, ignore a bundle of issues because their overarching theme is not that valuable yet. I try to have only one be bright green. That way I can see what is currently in play.
  • Question:Color: pastel blue. This is for any issue that needs further discussion. You could have questions for the person who submitted it or you need to talk to other devs about how to solve the problem. This tag makes it easier when you are looking at the list to see issues that need some kind of external input separate from code.
  • R-n: Color: white,grey, bright green. This follows the same pattern as the I tags. White for complete, grey for created, and green for active. They get a number depending on the release you are on. You can tag any issues for iterations that are part of the release with the release as well. I also use it as a tag to see where things are at in terms of bugs and other issues that are coming up before and after a release. So for example, you can tag all of the deploy/bug/features that are part of the next release with this tag. That helps track the punch list building up to your next big push out. Afterward, you can use it to collect bugs that come in after things have gone out or any issues that don’t have a clear theme. Once things have calmed down, you can move on to the next release tag and continue planning.
  • Ready To Test:Color: yellow. I use this when an issue has been submitted and I think it is done, but I need some kind of confirmation from the person who submitted the issue. This one became more important when I was working with remote developers. I can go in an look for this tag and then look at the tickets that I opened to see which ones I need to verify. If things look good I can close the ticket. If they don’t I remove the tag and add a comment, and it will end up back in the queue for work.
  • Technical Debt:Color: Orange. I did say keep all possible work here right? Technical debt is one of those things that is often discussed, but not often integrated into the work plan. Instead of burying it in a wiki page, or worse just letting it float in developers heads, put it in into the system. I find this really liberating. When I commit some kind of technical sin, I open a ticket and flag it. It allows me to stay focused on the feature without a ton of guilt. If I find a way to work on it after my feature work is done, fine, but this way it is captured and can be added to the schedule. You would be surprised at how much more of this stuff you would clear out if the list of what needed to be done is explicit.
  • Unsorted:Color: Dark Grey. I’m still playing with this one. When I add a feature and I do not see an iteration or release tag that is appropriate, I mark it unsorted. To me it means either this is a one off issue that needs to be put into a release, or it is the beginning of a new theme. It basically a reminder that things with this tag are probably never going to be worked on until some one organizes them.
  • Ux:Color: Bright Purple. This stands for User Experience. It was originally UI (User Interface), but it got broadened. You could conceivably have both. Mark it UX if it is related to either how something looks or its work flow. So if buttons are drawn in the wrong color, or there should be a confirmation on a delete. I break this out because a lot of the time, I partner with my brother who handles these kinds of issues. That’s also the reason for the color since he loves purple. Sometimes this serves as a warning to me that the feature or bug I’m taking is going to be more than just a quick codefest. It may require some styling or more thought about how to make something less confusing for the user.
  • Userid:Color:grey. Github Issues doesn’t let you say who is working/responsible for a ticket. The easy solution to this is to create a label with the userid of each team member. When you take a ticket, label it with your name. That makes it easy to see what things are unclaimed and who to talk to about the work.

Here is a sample from one of my projects. I’m just finishing up the first release – which included I-1,2,and 3.:



You may have to tweak some of my suggestions to fit the size of your team and your workflow, but at least now you have a starting point to take one of the features of github that is all to often squandered and turn it into something that enables you to keep focus on what you need to get done.

One Side Note

For those of you who spend as much time at the console as you do the web browser, github actually has a complete REST API for Issues. I ended up making heavy use of it when I migrated from another wiki in to github. I basically just created a csv in open office. Then I used their API to push all the information into Issues for me. That saved me a ton of time.

If you want something a little more flexible you can check out ghi. This is a command line tool that wraps all of that API. It give you another path to interacting with Issues. For example, I use ghi to make it easier to create technical debt tickets from the command line so I don’t get distracted by going to the website or leaving my work. A little bit helps.

Comments are closed.

Stuff I want to read

Shelfari: Book reviews on your book blog

Stuff I've Read

Shelfari: Book reviews on your book blog