GitHub issues are fantastic to track new features or bugs, who is assigned, categorize them, adding to projects and so on. At the same time, they’re also quite slow to create and creating a bunch of them consumes too much time.
One of the pain points I see with GitHub issues at work is that they’re cumbersome to create, particularly for those that are not developers or designers, like managers or testers, that want to report a bug without going through the process of creating them on GitHub.
A while ago I wrote about an app I was writing to speed up the creation of GitHub issues. I actually build the app but then I forgot to write about it here, so here’s the proper blog post. In this post, we’ll see:
- Why an app to create GitHub issues faster?
- Writing a batch of GitHub issues with plain text
- The tech stack behind the app
- More ideas to improve the creation of issues
Why an app to create GitHub issues faster?
The GitHub UI is usually ok to create an issue. Or two. And it’s ok for tech savvy people, like developers or designers. However, in our company Reconnect, sometimes after we develop a new feature, we ask our non-technical staff to test it. And that works great, because they usually find some issues. But it’s very consuming for them to go and jump through the GitHub issues UI. This is even more cumbersome when they have to create more than one issue and probably in different repositories.
If we quantify the number of times we shift our attention to create GitHub issues once we’ve reached the page to create an issue in the repository where we want to create them, it would be something more or less like this:
- enter the title
- move to the issue text box to enter the description
- go to the sidebar to assign the issue to someone
- move to the Labels block in the sidebar to add a label
- go and click the button to actually create the issue
That’s 5 times when we shift our attention from area to area! Too much attention shift for a task that is essentially writing and too much time spent refocusing. And what if you have to write an issue in a different repository? You have to navigate to that repository in a new tab or in the current one and that’s more time lost.
So how can you create GitHub issues more easily and faster? Wouldn’t it be easier if we could do it focused on a single place without having to shift our attention multiple times?
Writing a batch of GitHub issues with plain text
Writing is one of the most basic skills in devices, it’s more basic than even touch gestures. Because while those are specific to touch devices, you have to use a mouse or a trackpad on others. But writing is usually always the same. And GitHub issues are text so why not using text to create them without ever leaving our keyboard?
This app does exactly that: https://fast-issues.herokuapp.com/
You authorize this GitHub app and you can start writing issues in all your repositories. You just have to select a repository where you want to create an issue and start writing multiple issues, one on each line.
And it supports writing the title and description, assign it and label it. It only requires the issue title. The rest is all optional. You just need to follow a certain convention:
- the title comes first
- then, a pipe character separates the assignees. I chose it to be that way because at minimum, you need an issue and someone to work on it
- a second pipe character separates the issue description. It can have any length, but it can’t have any line breaks because that would start a new issue
- a third pipe character separates the labels
It supports multiple assignees and labels by separating them using a comma. So basically:
This is the title | username1, username2 | This is the issue description, as long as you want it but without line breaks. | Label 1, Label 2<br>This is another issue | username3 | And another issue description | Bug
Once it’s done, it’s a matter of clicking the Go! button and it will create all the issues. Each one will have you as the author. You can later go edit them to add images or videos, memes, anything.
If you need to create more issues in a different repository, just reselect it from the dropdown and start writing those issues. No more jumping through pages!
The tech stack behind the app
The repository for this app is located at https://github.com/eliorivero/fast-issues
The tech stack is particularly simple and entirely based on JavaScript:
- frontend built with React
- backend built with Node.js
- uses Express as the server
- and Octokit REST a library to work with the GitHub API
One thing to keep in mind is that we don’t want to surpass the limit of requests allowed by the GitHub Issues API. They recommend to let at least one second go by between requests so I paused the execution 1.5 secs between the creation of each issue.
From the initial prototype I made to the final version, I changed it from being a GitHub app to an OAuth app. It’s because the latter allows you to create issues and appear as the author.
More ideas to improve the creation of issues
I showed this to a friend and he told me that he had this idea of creating a Chrome extension to take a screenshot of a bug, annotate it, and submit it as a GitHub issue. I thought it was a great idea so I looked for a way to take a screenshot but inside a React app and quickly found html2canvas that allows to take screenshots and save them as PNG files.
Combining something like this with my tool to create the issues would be a nice solution that could be available in a React app during its development or staging cycle. Anyone testing the app could fire the issue reporting panel and submit a GitHub issue.
The only issue with that for now is that the GitHub API doesn’t allow to upload images, so they would have to be hosted somewhere else and have the link to that location inserted in this tool, but it’s definitely a good improvement.
So again, the app is at https://fast-issues.herokuapp.com/ and if you end up using it, let me know about it in the comments.
