6.1 Issues

Why GH-900 splits issues from pull requests

Domain 3 of GitHub Foundations (GH-900)—Collaborate using GitHub, 10–15% of the exam—opens with a compound skill: describe how to use issues, pull requests, and discussions. The January 2026 outline treats that as one bullet, but the three objects are not interchangeable. This section owns issues. Pull requests are the next section. Discussions are their own chapter. If a scenario is "track a bug," the answer is an issue. If it is "propose a code change," the answer is a pull request. If it is "ask the community a question with no owner," the answer is a discussion.

GitHub's About issues page is the product source. Issues let you plan, discuss, and track work. They are quick to create, live in a repository, usually have a clear owner, and GitHub itself still describes them as GitHub's bug-tracking system. That last phrase is exam-useful: issues are not a chat room. They are records of work the team intends to finish, defer, or close as not planned.

You can create an issue from the repository Issues tab, while adding a sub-issue, by converting a comment on an issue or pull request, from a specific line of code, or via a URL query. The same record can be opened from the web UI, GitHub Desktop, GitHub CLI, the REST and GraphQL APIs, or GitHub Mobile. GH-900 will not make you memorize every entry point. It will make you recognize that an issue is the durable work item those clients all create.

What an issue is for: tasks, bugs, and features

Use an issue when someone must do something in the repository:

• A bug reports unexpected or unintended behavior. Default label: bug.
• A feature or enhancement requests new behavior. Default label: enhancement.
• A task is work that is neither a defect nor a product idea—migrate a secret, update a screenshot, run a one-time backfill.
• Related uses GitHub still groups with issues: feedback on a specific feature, a question about files in the repository, and anything else you need to write down so the team can act.

An issue has a title, a Markdown body, a timeline of comments, and a right-hand sidebar of metadata: assignees, labels, type (on organizations that enabled issue types), projects, milestone, and Development (linked pull requests or branches). @mention a collaborator to notify them. Type # plus part of a title to autolink a related issue in the same repository. If you type the same comment often, use a saved reply (Domain 5 covers saved replies in more depth; here you only need to know they exist on issues).

Sub-issues and dependencies

Sub-issues create a parent/child hierarchy so a large piece of work breaks into smaller issues without stuffing everything into one body. You can nest multiple levels. That is the current replacement for retired tasklist blocks (GitHub announced the retirement in February 2025). You can still write Markdown task lists in an issue body; those are checklists, not a separate issue type.

Issue dependencies record blocking relationships: this issue is blocked by that one, or this issue is blocking other work. GH-900 will not ask you to draw a Gantt chart. It may ask whether GitHub can express "do not start B until A is closed." The answer is yes—issue dependencies—not a discussion poll.

Labels, assignees, milestones, and task lists

Metadata is how a pile of issues becomes a searchable backlog. GH-900 tests the purpose of each field, not every click in the sidebar.

Labels

Labels categorize issues, pull requests, and discussions inside one repository. Creating, editing, or deleting a label in repository A does nothing to repository B. Anyone with write access can create, edit, or delete labels. Anyone with triage access can apply or dismiss existing labels. New repositories ship default labels you should recognize by name:

Organization owners can customize those defaults for new repositories. Search uses label:bug. Quote multi-word labels: label:"help wanted".

Assignees

Assignees answer "who is working this?" You can assign yourself, anyone who commented, anyone with write permission, and organization members who have read permission. Issues and pull requests each support up to 10 assignees. Assigning does not grant extra repository permission and does not request a code review. It is ownership of the work item. Filter with assignee:USERNAME or assignee:@me. Repositories can also assign GitHub Copilot to an issue so Copilot opens a pull request; that is a Copilot-agent behavior Domain 4 covers, not a replacement for human assignees on GH-900's collaboration questions.

Milestones

A milestone groups issues and pull requests toward a named outcome, often a release or a date. The milestone page shows a description, due date, completion percentage, counts of open and closed items, and the list itself. You can drag to prioritize unless the milestone has more than 500 open issues. Search with milestone:"sprint-12". A label says what kind of work; a milestone says which batch it ships with.

Task lists

A task list is Markdown checkboxes in a comment or issue body:

- [x] Reproduce on main
- [ ] Write a failing test
- [ ] Open a pull request that closes this issue

Incomplete items use - [ ]; complete items use - [x]. In an issue body, GitHub adds extra behavior: progress appears on the repository issue list; closing a referenced issue checks that box; hovering a task lets you convert it to an issue; referenced issues show they are tracked by the parent. You cannot create task-list items inside closed issues or issues that already have linked pull requests. Tasklist blocks (the old structured UI) are retired; sub-issues are the hierarchy replacement. The exam still expects the Markdown checklist syntax because it is how many teams write acceptance criteria.

Integration: Projects, mentions, and auto-close

Issues plug into the rest of GitHub. Mentioning an issue from another issue or pull request creates a reference on both timelines. Putting a supported keyword in a pull request description (or a commit message) links and can auto-close the issue. GitHub documents the keyword families as:

• close, closes, closed
• fix, fixes, fixed
• resolve, resolves, resolved

Same-repository syntax is Closes #10. Cross-repository syntax is Fixes octo-org/octo-repo#100. Multiple issues each need a full keyword: Resolves #10, resolves #123. Colons and capitalization are allowed (Closes: #10, CLOSES #10). The pull request must target the repository default branch. Keywords on a pull request into any other branch are ignored: no link, no auto-close. Closing keywords in a commit message still close the issue when that commit merges to the default branch, but the containing pull request is not listed as a linked pull request. Section 6.3 goes deeper on the Development sidebar; this section only needs the issue-side effect: the work item can close itself when the fix lands on default.

GitHub Projects (Domain 5) consume issue metadata so you can filter and view the same issues on a board or table. You do not need a Project to use issues. You need issues if you want Projects to track real work instead of empty cards.

Subscribe to an issue to get comment notifications. Assigning yourself is the fastest way to find "my work" later with assignee:@me.

Issues vs Discussions, and converting

GitHub's Communicating on GitHub guide is the decision table GH-900 wants.

Issues fit when you want to keep track of tasks, enhancements, and bugs; file a bug report; share feedback about a specific feature; or ask a question about files in the repository. They are repository-specific and usually have a clear owner.

Discussions are the forum. They fit questions that are not tied to specific files, news you want to share, open-ended conversation, and announcements. They often do not have a clear owner and often do not result in an actionable task. A discussion can span ideas across a community; an issue is a work record in one repo.

When a conversation started as an issue but is really a forum thread—"should we adopt a code of conduct?" with no implementation ticket—convert the issue to a discussion. Conversion preserves the comments instead of closing a fake bug as wontfix. The reverse mistake is also on the exam: do not file an issue titled "Welcome newcomers" and leave it open forever. That is a discussion.

Templates and issue forms (section 6.3) exist so incoming issues contain the fields you need: repro steps, version, expected versus actual. Community health files such as CONTRIBUTING.md tell people when to open an issue versus a discussion. You can report comments that violate GitHub's Community Guidelines; that is moderation, not work tracking.

Exam scenarios and traps

• "I found a crash in auth.ts" → issue (bug), not a discussion and not a pull request until someone has a fix.
• "What do people think about rewriting the CLI in Rust?" → discussion until it becomes a tracked project.
• A labeled, assigned, milestoned discussion is a trick option. Labels can apply to discussions, but assignees and auto-close keywords are issue/PR collaboration, not the discussion model.
• Creating a label requires write access; applying a label requires triage. Do not say only admins can tag a bug.
• Ten-assignee cap: you cannot assign the entire 40-person org to one issue.
• Closes #10 on a pull request into release-2 does nothing if release-2 is not the default branch.
• Task lists in the body are not the same as sub-issues. Checklists show progress; sub-issues are real child issues.
• Closing an issue as completed versus not planned is a close reason you can later search with reason:completed or reason:"not planned". It is not a label.

If you can look at a one-line scenario and answer "is this work we will close, or a conversation we will answer?" you have Domain 3's issue skill. Attach labels so it is findable, assignees so it is owned, a milestone so it is dated, and a task list or sub-issues so progress is visible—then let a pull request close it when the default branch moves.