How to Track Work with GitHub Issues

Requests scattered across chat threads, emails, and meeting notes have a way of disappearing. Someone mentions a broken link, everyone agrees it should be fixed, and a month later nobody remembers who was supposed to fix it. If you've ever repeated the same request three times, you've felt that cost. Issues exist to stop that from happening.

GitHub issues give that work a permanent home next to the code. An issue describes one problem, idea, or task, and it stays open until someone resolves it. Comments keep the whole conversation in one place, right next to the work it describes. Labels sort issues by type, assignees show who owns them, templates make sure every report includes the right details, and linking an issue to a pull request can close it automatically once the fix is merged. For designers and product managers, issues are often the easiest way to take part in a project without changing a single file.

A useful issue can be understood by someone who wasn't in the room. Clear titles, enough context, and one task per issue turn a list of complaints into work a team can finish. Before writing a new issue, a quick search often turns up an existing one to comment on instead.

Issues as a shared to-do list

An issue is a single item of work tracked in a repository: a bug, an idea, a question, or a task ^[1]. Each one gets a number, like #14, a title, a description, and a comment thread, and it stays open until someone closes it.

Because issues live next to the code, they connect to everything else. Mentioning #14 in another issue or a pull request creates a reference between them, so anyone reading issue #14 later can follow the trail from the original report to the change that fixed it.

For people who don't write code, issues are often the main way to contribute. Reporting a bug, suggesting new copy, or attaching a design for feedback all happen in issues, in plain language, without editing a single file.

Writing clear issue titles

An issue title is what people see in lists, notifications, and search results, usually without opening the issue. A good title names the problem and where it happens, like Contact form doesn't send on mobile Safari. A vague one, like Bug or Website broken, forces everyone to open it just to learn what it's about.

Specific titles also prevent duplicates. Before filing a new issue, a quick search finds reports of the same problem, but only if earlier titles used the words people search for. Contact form matches a search for a contact form problem. Please fix ASAP matches nothing useful.

The description carries the rest: steps to reproduce the problem, what was expected, what happened instead, and a screenshot if it helps. A clear title and a structured description together let someone fix the issue without a follow-up conversation.

Pro Tip! Starting a title with the affected area, like Checkout: or Menu page:, makes long issue lists easier to scan.

Issue templates for consistent reports

Issue templates ask reporters for the right details up front. When a repository has them, selecting New issue opens a chooser, with options like Bug report or Feature request, and each template pre-fills the description with headings and prompts.

Templates live in the repository, in a hidden .github/ISSUE_TEMPLATE folder on the default branch ^[2]. Markdown templates suggest a structure. Issue forms, written in YAML, a simple settings format, go further, with labeled fields, dropdowns, and required inputs, so a bug report can't be submitted without, for example, the browser and the steps to reproduce.

For the team, templates mean less back-and-forth: every report arrives with the same structure, which makes issues faster to sort and easier to compare. For the reporter, the prompts take away the guesswork about what to include.

Labels for sorting issues

Labels are colored tags that sort issues, pull requests, and discussions by type, priority, or area. Every new repository starts with a default set, including bug, documentation, enhancement, good first issue, and question^[3]. Teams usually add their own, like design or priority: high.

Labels make long lists manageable. Selecting a label shows every issue that carries it, so a designer can see all open design issues in one view. The good first issue label has a special role: GitHub uses it to point newcomers to a safe place to start.

A short, agreed set works better than dozens of overlapping labels. If bug, defect, and broken all exist, people apply them inconsistently and filters miss issues. Agreeing on a few labels and what each one means keeps sorting reliable.

Assignees and milestones

An assignee is a person responsible for an issue or pull request. Each one can have up to 10 assignees ^[4], but a single clear owner usually works better. When several people share an issue, it's easy for each to assume someone else is handling it.

A milestone groups issues and pull requests around a goal or a date, like Spring launch. Its page shows the due date, how many items are open and closed, and a completion percentage, which gives a quick sense of how close the goal is ^[5].

Both live in the issue's sidebar and are easy to change. Reassigning an issue when priorities shift, or moving it to a later milestone, keeps the list honest about who is doing what, and when.

Linking issues to pull requests

A pull request can close an issue automatically. A keyword followed by the issue number in the pull request description, like Closes #14, Fixes #14, or Resolves #14, links the two, and merging the pull request closes the issue ^[6].

The link shows up on both sides. The issue points to the pull request, so anyone checking it can see a fix is in progress, and the pull request lists the issue it resolves. Links can also be added by hand from the Development section of the sidebar.

The automatic close only works when the pull request targets the repository's default branch, usually main. A pull request merged into a feature branch leaves the issue open, which is a common reason an issue stays open after its fix was merged.

Pro Tip! Keywords work in commit messages too, so a commit saying Fixes #14 closes the issue once it reaches the default branch.

Issues vs. discussions

Some repositories also use Discussions, a forum-style space for conversations that aren't tasks. Issues suit specific, finishable work like bug reports and planned improvements, while discussions suit open-ended ideas, questions, and brainstorming that may never have a single answer ^[7].

A question like How should the menu page handle seasonal items? fits a discussion. Once the team agrees on an approach, the concrete work becomes an issue. When something lands in the wrong place, people with triage permission can convert an issue into a discussion or create an issue from a discussion.

Keeping the two apart keeps the issue list actionable. When every idea and question becomes an issue, real bugs get buried, and the list stops reflecting what actually needs doing. Discussions have to be turned on by an administrator, so not every repository has them.

Mentions and notifications

Typing @ followed by a username mentions that person and sends a notification, and mentioning a team, like @sweetcrumbs/design, notifies everyone on it ^[8]. Mentions pull someone into a conversation right where the context is, which beats a separate message in chat.

GitHub also subscribes people to conversations automatically: when they open an issue, comment on it, are assigned to it, or are mentioned in it ^[9]. Each issue has a Subscribe or Unsubscribe button in its sidebar, so following one conversation closely, or stepping away from one, takes a single click.

On busy projects, notifications pile up quickly. Mentioning only the people who need to act, with a clear question, keeps mentions meaningful and gets faster answers than a list of every name that might be interested.

Planning work with GitHub Projects

GitHub Projects turns issues and pull requests into a planning tool. The same items can appear as a spreadsheet-like table, a board with columns like Todo, In progress, and Done, or a roadmap laid out on a timeline ^[10].

Projects stay in sync with the work. Built-in workflows can move an item to Done when its issue closes, and custom fields, like priority, size, or design status, add the details a team plans around. Draft items capture ideas before they become real issues.

For product managers and designers, a project is often the most useful view of GitHub. It answers the planning questions of what's next, what's blocked, and who's on it, without anyone opening a single file.