How to Use GitHub Issues

Planning a project of any kind can be time-consuming. This is especially true in the development sphere, where details are often of critical importance. At a minimum, planning a project tends to involve setting objectives, defining timeframes, and specifying tasks to be performed. GitHub Issues accommodates these actions and more in a simple, flexible way.

By using GitHub Issues, you can blend proper planning functionality into the ongoing operations of your codebase, creating a fully integrated issue-tracking workflow within GitHub. But you'll need to know how GitHub Issues works and how you can use it most effectively.

How GitHub Issues works

GitHub Issues is designed to keep your team's planning efforts as close to your actual codebase as possible. This is accomplished through the use of so-called "project tables." These are specialized spreadsheet-like layouts meant to offer you a familiar means of managing issues in a single place. The main benefit of this feature over simply using a spreadsheet document to do the same is its deep integration with GitHub and the wealth of additional automated functionality that it enables. Unlike separate spreadsheets, issues tracked directly in GitHub are intrinsically linked to your codebase and the work that your team is currently doing. This means that you will not need to manually update references to said work as development progresses or otherwise realign a disconnected spreadsheet with information from a separate source of truth.

Besides its fairly familiar table layout, GitHub Issues are also viewable in a board layout that can provide a more visually appealing view of all issues your team has opened so far. Issues are groupable and easy to interact with in both this view and the default table layout, simplifying management without sacrificing accuracy or flexibility in any way.

Creating Issues

Issues are easy to create and allowing your project's end users to contribute by opening new issues can go a long way toward aiding in the development process. There are a few important actions that you should consider taking when it comes to creating new issues:

• Adding tasks: Tasks are a particularly important component of a well-defined issue as they allow for progress to be tracked at a highly granular level with relative ease and clarity.

 You can easily create a task list by adding line items to your issue's description field in which the first characters are either "- [ ]" or "- [x]." Progress toward task list completion shows up in other views of your repository's issues, allowing for at-a-glance assessments that effectively boost your team's productivity.

• Adding custom fields: Although the default fields available for classifying individual issues on GitHub are great, the inclusion of custom fields vastly enhances your planning possibilities to better match your own unique workflow. You can quickly create new custom fields for your project's issues from the Issues table layout and fill in pertinent details, including a name, select mode (single, etc.), and options that can be chosen. These details are even visible within individual issues, allowing team members to view them wherever they like, without modifying their own workflow in the process.
• Saving views: Once you have customized the details of your Issues layout, you can actually choose to save them all as a single view. This view can then be shared among the members of your team to keep everyone on the same page.

Managing discussions

GitHub Issues makes it pretty easy for your team to interact and discuss details that apply to the different tasks they have to handle. Every issue comes complete with a unique comment thread that can be used to coordinate ideas and clarify complex needs. Each comment benefits from markdown characters, emojis, and more that can help make things easier to read through.

To further simplify issue-based communication, GitHub offers options for users to subscribe to individual issues and even the repository as a whole (via the Watch button) so that notifications of changes are highlighted in their accounts and a digest is sent to their email addresses every day.

How you can use GitHub Issues

GitHub Issues is designed to work smoothly across multiple environments, including both your browser and your terminal. GitHub Issues is even available on mobile via GitHub's native Android and iOS apps. All of the information created in GitHub Issues is available as a part of your repository, simplifying its use dramatically.

Use issue forms and templates to help keep your repository's issues consistent. Forms for your issues can be custom-coded with YAML syntax, allowing for everything from specific inputs to default assignees to be chosen in advance whenever someone opens a new issue.

Get more out of GitHub with Mergify 🥰

Having a great issue-tracking system at your disposal is just one of many ways that GitHub can be used to empower your team and streamline development efforts. Adding Mergify to the mix opens the door for all sorts of improvements to your workflow, including automatic code review assigning and merge operations that require no manual intervention to start. Learn more today with a free demo.