GitHub Issues: The What, Why, and How

Every agile team and software project needs a tool to track and organize work. But who wants to interrupt work to track work?

You need a tracking tool that’s part of your development repository to help you stay focused on the task at hand while keeping your project plans up to date.

A well-maintained tracker helps you manage a collaborative project and gives you visibility into the progress. You can gain a bird’s-eye view of what needs to be done and prioritize your time and resources.

If you use GitHub as your repository, then GitHub Issues is a great tracking tool to keep your work and plans in sync. You don’t have to navigate away from the platform to make your entries, and you can track tasks as you complete them.

Let’s see how you can take advantage of GitHub issues’ fast and responsive user interface, cross-project referencing capability, collaborative features, seamless integration with pull request and Git repository, and other robust functionalities.

What Is GitHub Issues and What Can It Do For You?

You get GitHub Issues as part of a git repository. Since it’s part of the repo, you don’t have to worry about integration. It works right out of the box, so you can hit the ground running right away.

GitHub Issues allows you to create text-based descriptions of tasks, bugs, changes, and updates in your software development project to keep track of them and address them systematically.

Most software development teams use GitHub Issues for tracking bugs and requesting features. It can also help manage discussions, process support requests, track relationships and dependencies, and gather documentation feedback to help your team stay focused and streamline workflows while collaborating seamlessly.

You can create issues on different platforms, including the web UI, GitHub Desktop, GitHub CLI, GraphQL and REST APIs, or GitHub Mobile, and use GitHub Issues for various purposes:

• Create a to-do list: Break down a task into action items and assign them to team members. You can also assign labels (e.g., bug, enhancement) to organize the entries. The platform supports markdown, so you can create a task list with checkboxes to divide an item into smaller pieces and track the progress.
• Set milestones: Set a deadline for specific to-do items and track their progress by creating milestones on the issues tab. The milestone meter will update when each entry is closed to help you visualize how close you are to meeting the deadline.
• Comment on an issue: Leave comments on an issue to discuss and collaborate with other team members. You can get feedback or ask others to vote on various options. You can also tag someone with an @ symbol or share your thoughts with an emoji.
• Close an issue: Close an issue with a note explaining why it’s closed (e.g., you have fixed a bug), so others in your team can reference it in the future. You can also reopen an issue if it’s been closed accidentally.

How to Get the Most Out of GitHub Issues

Follow these GitHub Issues best practices to get the most out of this handy tool:

1. Start With the Default Setting

The default setting is a good starting point when you set up a new repo and don’t have many issues to track. All the forms are enabled, and GitHub users can interact with each other, submit reports, and comment on discussions without restrictions.

You can get a feel for the team dynamic at the early stage of the project and figure out what works best. However, be prepared to handle some back-and-forths. You may also need to review stale issues and close them regularly to avoid confusion.

When your repo matures and the issue traffic increases, you’ll need to establish a structure for the reporting workflow—the following best practices can help.

2. Use Search To Avoid Submitting Duplicate Issues

Team members should use the search feature to see if a similar issue has already been submitted before creating a new one. They can get an update on the issue’s status, upvote the issue, and learn about workarounds.

GitHub Issues doesn’t automatically search for possible duplicates as you enter a new issue. Create a CONTRIBUTING.md doc in your repo’s root and describe your issue reporting workflow to encourage team members to search before submitting a new report.

3. Establish an Issue Reporting Structure

As the number of reports grows, you should define what issues to accept, what information each entry must contain, and standardize how team members submit bugs and create new issues. Also, you may or may not want to allow discussions in your issue tracker.

Encourage reporters to make the issue title descriptive and include a reproducible code example when submitting a code bug. You can also add metadata to an issue to provide additional information.

Create issue forms with GithHub’s template builder to streamline reporting. You can configure the template chooser in your repo so team members can only use the suggested issue templates. You may also direct reporters to external sites for activities that you don’t allow in the repo (e.g., discussion.)

4. Create a Separate Workflow For Reporting Vulnerabilities

You don’t want vulnerabilities to be reported and tracked publicly because that’d give you no time to take action. Instead, provide a separate reporting path for this type of disclosure to report the issue privately until you release a patch.

The example below shows how you can create a separate workflow for reporting vulnerabilities:

5. Organize Issues with Labels

You can apply multiple labels to any issue, categorize issues, chunk a project into manageable pieces, and sort the entries in different ways. Here are some examples:

• Break down a project by areas of responsibility.
• Mark non-triaged issues to ensure every entry is processed.
• Notate open issues that require more details from the reporter.
• Identify issues that are open for external contributions.

You’ll get a set of default labels when you open a GitHub repository. You can use them as-is or make changes (e.g., add a prefix or change the color.) Don’t overuse labels—too many can add to the confusion, which defeats the purpose of using them in the first place!

6. Manage Workflows and Communication

You can tag collaborators with the @username syntax, and they’ll receive an email notification. When you mention a user who wasn’t involved in an issue, make it clear if you’re keeping them in the loop or need them to take a specific action.

Assign each issue to a team member to ensure that nothing falls through the cracks. If you have a private repo where only members with permissions can create and comment on issues, you can set assignees right away. If you allow external users to submit new issues, leave them unassigned and review them regularly to assign owners.

Lastly, close issues when they’re resolved to minimize confusion. You can use the Closes #issue_number syntax (e.g., Closes #1) to auto-close issues from pull request descriptions and commit messages once the commit is pushed into the main branch. You can also use GitHub Action’s automation feature to close issues.

Make GitHub Issues Work Harder For You

GitHub Issues is a lightweight but capable issue tracker that gives you a sufficiently scalable framework to manage issue reporting. Since it’s part of the GitHub platform, you don’t need to invest in a separate issue tracking tool or have your team spend extra time logging into another software to report issues.

But as robust as GitHub’s code and project management features are, there’s a missing piece of the puzzle—a detailed time-tracking tool that can give you the insights to create accurate estimates and inform resource allocation.

A time-tracking app that integrates with GitHub Issues (e.g., 7pace Timetracker) allows team members to record the time spent working on each issue without entering their time into a separate tool after the fact, which may affect the accuracy and granularity of the entries.

You can ensure that your team is on track by pulling real-time reports on each project, estimating the time required to reach a milestone, and course-correct when necessary. You’ll also know which work items your team has spent time on and the amount of effort involved.

The data can give you a clear understanding of each work item and your team’s velocity. You can gain visibility to make accurate estimations for future sprints. You can also identify and investigate roadblocks to prevent them in the future.

7pace for GitHub helps you get more out of GitHub Issues. Developers and software teams can track time where they work, associate the hours to each work item, pull real-time reports, and gain granular insights on how they spend their time without making time reporting a cumbersome afterthought.

Sign up for 7pace for GitHub to see how effortless it can be to manage your issues and projects with granular and accurate historical data.