Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Issues, Projects and Discussions

Issues: Tracking Work on GitHub

Use GitHub Issues to track bugs, tasks and ideas: write a useful issue, mention people, assign work, use task lists and sub-issues, link pull requests and search with filters.

An issue is a numbered, discussable record of something that needs attention: a bug, a feature request, a question, a chore. Issues live in a repository, share one numbering sequence with pull requests (#1, #2, ...) and give your team a single place to say "this is what we are going to do, and here is what we know". They are enabled by default on new repositories and can be switched off under Settings > General > Features.

Writing a good issue

A good issue lets someone who was not there understand and act on it. For a bug report, include:

  1. A specific title: "Crash when the cart is empty at checkout", not "Doesn't work".
  2. What you expected and what happened.
  3. Steps to reproduce, numbered, from a clean state.
  4. Environment: version, operating system, browser.
  5. Evidence: error text (in a code block), screenshots or a screen recording.
MARKDOWN
**Version:** 2.4.1, Windows 11, Firefox 130

**Steps**
1. Add any item to the cart.
2. Remove the item.
3. Click "Checkout".

**Expected:** A message saying the cart is empty.
**Actual:** White screen; console shows `TypeError: Cannot read properties of undefined (reading 'total')`.

For a feature request, describe the problem you want solved before the solution, and who benefits. Search first: GitHub shows similar issues as you type the title, and duplicates waste everybody's time. Be kind, stay on topic, and remember that maintainers are often volunteers.

The issue page

  • Title and number: the number is permanent; refer to it as #42 in the same repository or owner/repo#42 elsewhere.
  • Description and comments: Markdown with mentions, reactions, file attachments, and quoted replies (select text and press r).
  • Sidebar: Assignees, Labels, Projects, Milestone, Development (linked branches and PRs), Participants and notification controls.
  • Status: Open or Closed, and a closed issue records why: completed, not planned or duplicate.

Mentions, references and notifications

  • @username or @org/team notifies that person or team.
  • #42 creates a cross-reference: the other issue or PR shows "mentioned this issue" in its timeline.
  • A full URL to an issue or commit turns into a short rendered reference.
  • Subscribe or Unsubscribe on the sidebar controls notifications for that one issue; you are automatically subscribed when you comment, are mentioned or assigned.
JS Stand-in: extract references from text

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Assigning and closing

Assign an issue to the people responsible for it (up to ten). Assign yourself with the sidebar link, or with gh issue edit 42 --add-assignee @me. Close it when the work is done:

  • Automatically: the PR description contains Closes #42 and merges into the default branch (see Pull Requests: The Basics).
  • Manually: the Close issue button, with the reason (completed or not planned); gh issue close 42 --reason "not planned".

Closed issues can be reopened. Pin up to three important issues at the top of the issue list, and transfer an issue to another repository in the same account or organization when it was filed in the wrong place.

Task lists and sub-issues

A Markdown task list creates a checklist whose progress is summarized in the issue list:

MARKDOWN
## Plan
- [x] Design the settings screen
- [ ] Add toggle component
- [ ] Persist the choice
- [ ] Update documentation

For bigger work, sub-issues let you nest issues under a parent: add them from the issue's Create sub-issue or Add existing issue controls. The parent shows a progress bar, and you can nest several levels. Prefer sub-issues for work tracked by different people, and plain checkboxes for small steps within one person's task.

JS Stand-in: task list progress

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Searching and filtering

The search box on the Issues tab accepts qualifiers. Some of the most useful:

Query Finds
is:open is:issue Open issues only (no PRs)
author:ada Opened by ada
assignee:@me Assigned to you
label:bug label:"help wanted" Both labels
no:assignee Nobody is working on it
milestone:"v2.0" In a milestone
created:>2026-01-01 Newer than a date
comments:>10 Hot discussions
sort:updated-desc Most recently updated first
crash in:title Text in the title only

Add - to negate (-label:wontfix), and combine freely. You can save a useful filter as a view by bookmarking its URL, or build one in a project (next lessons). The same syntax works in gh issue list --search "..." and in the REST API's search endpoint.

JS Stand-in: filter issues like the search box

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What belongs in a good bug report?

    Reproducible reports are far easier to fix.
  2. 2. How do you refer to issue 42 in another repository octo-org/api?

    Use owner/repo#number across repositories.
  3. 3. Which query finds open issues nobody has been assigned to?

    no:assignee finds issues without assignees.
  4. 4. What are the two reasons you can choose when closing an issue manually?

    GitHub records whether the issue was completed or closed as not planned (a duplicate is a variant of not planned).

Summary

  • Issues are numbered, discussable records of bugs, tasks and ideas; write them to be reproducible and specific.
  • Use mentions, # references, assignees, task lists and sub-issues to organize the work.
  • Close via a merged PR keyword or manually with a reason.
  • Search qualifiers such as is:open, label:, assignee: and no: find anything quickly.

Next: Labels, Milestones and Templates