GitHub Issues: Creating, Labeling, Assigning, Milestones, and Closing via Commit
GitHub Issues is the platform's built-in tool for tracking bugs, feature requests, and general tasks directly alongside a project's code — briefly mentioned in Module 4 and now covered in full. This lesson covers creating issues and the organizational tools around them: labels, assignees, milestones, and the same automatic-closing behavior via commit messages that the PR best practices lesson introduced for pull requests.
Learning Objectives
- Create a new GitHub issue to track a bug, task, or feature request.
- Apply labels to categorize and filter issues.
- Assign an issue to a specific person responsible for addressing it.
- Group related issues under a milestone, and close an issue automatically via a commit message.
Key Terms to Know Before Using GitHub Issues
- GitHub Issue: A trackable unit of work — a bug report, feature request, or task — stored directly within a GitHub repository, supporting comments, labels, and other metadata.
- Label: A colored tag applied to an issue (or pull request) for categorization, such as 'bug', 'enhancement', or 'good first issue'.
- Assignee: A specific person designated as responsible for addressing a particular issue.
- Milestone: A collection of issues and pull requests grouped together toward a shared goal, often representing a specific release or project phase, with an optional due date and progress tracking.
How GitHub Issues Actually Work
Creating a new issue, via a repository's 'Issues' tab, requires a **title** and typically a **description** explaining the bug, request, or task in detail — the next lesson covers issue templates, which help standardize this description for consistency, similar to PR description templates from an earlier lesson.
Once created, several organizational tools help manage issues at scale:
**Labels** are colored tags applied to categorize issues — common examples include `bug`, `enhancement`, `documentation`, `good first issue` (a widely recognized convention flagging beginner-friendly tasks for new contributors), and `wontfix`. Labels can be filtered on directly from the Issues tab, making it easy to find, for example, every open bug, or every issue suitable for a newcomer's first contribution.
**Assignees** designate a specific person (or people) responsible for addressing an issue. This is distinct from simply commenting on an issue — an assignee shows up in filtered views and notifications specifically as the person expected to act on it, helping avoid the ambiguity of an issue nobody has explicitly claimed.
**Milestones** group related issues and pull requests together toward a shared goal — commonly a specific release version (like 'v2.0') or project phase — and automatically track progress as a percentage based on how many of the milestone's issues have been closed. This gives a quick, visual sense of how close a release or phase is to completion, without needing to manually tally individual issues.
Finally, exactly like the pull request closing-keyword behavior from the PR best practices lesson, an issue can be **closed automatically via a commit message**, using the same recognized keywords (`closes`, `fixes`, `resolves`) followed by the issue number:
```
git commit -m "fix: correct bulk discount calculation, closes #42"
```
When a commit containing this message is pushed to (and, if part of a PR, merged into) the repository's default branch, GitHub automatically closes issue #42 — the same underlying mechanism covered for pull request descriptions, just triggered directly from a commit message instead. This reinforces a theme from this module: GitHub issues and the actual code changes that resolve them stay tightly, automatically connected, rather than requiring manual bookkeeping to keep them in sync.
GitHub Issues Workflow: Visual Walkthrough
Draw a GitHub Issues list view mockup with three example issue rows: '#40 Bug: Login button unresponsive on mobile [label: bug] [assignee: Rohit]', '#41 Feature: Add CSV export [label: enhancement] [assignee: unassigned]', '#42 Bug: Bulk discount miscalculated [label: bug, good first issue] [assignee: Asha] [milestone: v2.0]'. Draw an arrow from issue #42 to a commit message box: 'git commit -m "fix: correct bulk discount, closes #42"', which then arrows into issue #42 flipping to a 'CLOSED' status badge.
GitHub Issue Features: Quick Reference Table
| Feature | Purpose |
|---|---|
| Labels | Categorize issues (bug, enhancement, good first issue, etc.) for filtering |
| Assignees | Designate specific person(s) responsible for addressing an issue |
| Milestones | Group related issues/PRs toward a shared goal, tracking progress automatically |
| Closing keywords in commits | Automatically close an issue when a commit referencing it reaches the default branch |
Closing an Issue via Commit Message: Syntax and Examples
# Closing an issue automatically via a commit message
git add checkout.js
git commit -m "fix: correct bulk discount calculation, closes #42"
git push
# If this commit is part of a pull request, issue #42 closes automatically
# once that pull request is MERGED into the default branch (not just when pushed to a branch)
# Recognized closing keywords (any of these work, followed by an issue number):
# closes #42 fixes #42 resolves #42Breaking Down the GitHub Issues Example
This commit message includes the closing keyword `closes #42` directly within its text. If this commit is pushed straight to the repository's default branch, the issue closes immediately; if it's part of a feature branch proposed via a pull request, the issue only closes once that pull request is actually merged into the default branch, keeping the automatic closing behavior tied to the point where the fix genuinely becomes part of the project's mainline history, not merely when work on it begins.
How GitHub Issues Are Used on Real Engineering Teams
- Nearly every actively maintained open-source and commercial software project uses GitHub Issues as its primary bug and feature tracking system, often integrated with project boards (a later lesson this module) for broader workflow visualization.
- The 'good first issue' label convention is so widely recognized across open source that GitHub itself provides dedicated search and discovery tools specifically for newcomers looking for issues tagged this way across all of GitHub.
- Release managers commonly use milestones to track exactly which issues and pull requests are targeted for an upcoming version, using the automatic progress percentage as a quick health check leading up to a release date.
- Automatic issue closing via commit messages is a routine, expected part of daily workflow on most professional teams, keeping the issue tracker synchronized with actual shipped work without manual bookkeeping.
GitHub Issues Interview Questions and Answers
Q1. What is the difference between a label and an assignee on a GitHub issue?
A label is a colored tag used to categorize an issue (such as bug, enhancement, or good first issue) for filtering and organization. An assignee is a specific person explicitly designated as responsible for addressing that particular issue, distinct from simply commenting on or being interested in it.
Q2. What is a GitHub milestone, and what does it help track?
A milestone groups related issues and pull requests together toward a shared goal, commonly a specific release version or project phase. It automatically tracks progress as a percentage based on how many of its associated issues have been closed, providing a quick visual sense of how close that goal is to completion.
Q3. How can you close a GitHub issue automatically using a commit message, and when does the closing actually happen?
Include a recognized closing keyword (closes, fixes, or resolves) followed by the issue number in the commit message, such as 'closes #42'. If that commit is pushed directly to the default branch, the issue closes immediately; if it's part of a pull request, the issue only closes once that pull request is actually merged into the default branch.
GitHub Issues Quiz: Test Your Understanding
1. What is the purpose of a label on a GitHub issue?
- To assign a specific person responsibility for the issue
- To categorize the issue for filtering and organization
- To automatically close the issue
- To delete the issue after 30 days
Answer: B. To categorize the issue for filtering and organization
Explanation: Labels are colored tags (like bug, enhancement, or good first issue) used to categorize and filter issues, distinct from assigning a specific person to address them.
2. What does a GitHub milestone automatically track?
- The exact time each issue was created
- Progress as a percentage, based on how many associated issues/PRs have been closed
- Who commented most on an issue
- The total file size of the repository
Answer: B. Progress as a percentage, based on how many associated issues/PRs have been closed
Explanation: Milestones group related issues and pull requests toward a shared goal, automatically calculating and displaying a completion percentage based on how many of them have been closed.
3. Which commit message would automatically close GitHub issue #42 once merged into the default branch?
- "update checkout logic, issue 42"
- "fix: correct discount calculation, closes #42"
- "see #42 for details"
- "mentions issue #42"
Answer: B. "fix: correct discount calculation, closes #42"
Explanation: Only commit messages containing a recognized closing keyword (closes, fixes, or resolves) directly followed by the issue number trigger GitHub's automatic issue-closing behavior — plain mentions of an issue number do not.
Common Mistakes When Using GitHub Issues
- Leaving issues unassigned indefinitely, creating ambiguity about who is actually responsible for addressing them.
- Using inconsistent or ad-hoc labels across a project, making filtering and organization far less effective over time.
- Forgetting that a closing keyword in a commit on a feature branch doesn't close the issue until that branch's pull request is actually merged into the default branch.
- Not using milestones for larger, multi-issue efforts, missing out on the automatic progress tracking they provide toward a release or goal.
GitHub Issues: Exam-Ready Quick Notes
- Labels: categorize issues for filtering (bug, enhancement, good first issue, etc.).
- Assignees: designate specific person(s) responsible for an issue.
- Milestones: group issues/PRs toward a shared goal, auto-tracking completion percentage.
- Closing keywords in commits (closes/fixes/resolves #N): auto-close the issue once merged into the default branch.
GitHub Issues: Key Takeaways
- GitHub Issues provides a full-featured tracking system for bugs, tasks, and feature requests, directly integrated with a project's code.
- Labels, assignees, and milestones together provide the organizational structure needed to manage issues effectively at scale.
- Closing keywords in commit messages keep the issue tracker automatically synchronized with actual completed, merged work.
Frequently Asked Questions About GitHub Issues
Q1. How do I create a new GitHub issue?
Navigate to a repository's 'Issues' tab and select 'New issue', then provide a title and description explaining the bug, feature request, or task. Some repositories provide issue templates (next lesson) to help structure this.
Q2. What are labels used for on GitHub issues?
Labels are colored tags used to categorize issues, such as bug, enhancement, or good first issue, making it easy to filter and find specific types of issues across a repository.
Q3. What is a milestone on GitHub?
It's a way to group related issues and pull requests together toward a shared goal, commonly a specific release version, automatically tracking what percentage of that milestone's issues have been closed.
Q4. How do I automatically close an issue when I fix it?
Include a recognized closing keyword — closes, fixes, or resolves — followed by the issue number in your commit message, such as 'fixes #42'. The issue will automatically close once that commit reaches the repository's default branch.
Q5. What is the difference between assigning an issue and just commenting on it?
Assigning an issue explicitly designates a specific person as responsible for addressing it, showing up in filtered views and notifications as such. Commenting is just participating in the discussion without necessarily taking ownership of resolving it.
Summary
GitHub Issues provides a built-in system for tracking bugs, feature requests, and tasks directly within a repository. Labels categorize issues (such as `bug`, `enhancement`, or the widely recognized `good first issue` convention) for easy filtering, while assignees designate specific people responsible for addressing a given issue. Milestones group related issues and pull requests toward a shared goal, such as a specific release, automatically tracking completion progress as a percentage. Finally, issues can be closed automatically using the same closing-keyword convention introduced for pull requests — a commit message containing `closes #42` (or `fixes`/`resolves`) will automatically close that issue once the commit reaches the repository's default branch, whether pushed directly or merged via a pull request, keeping the issue tracker synchronized with actual shipped work without manual bookkeeping.