What Are Issues?
Various situations come up during a project:
- "Clicking this button causes an error!"
- "It would be great to add dark mode."
- "This section of the docs seems incomplete."
GitHub Issues is a system for managing tasks, bugs, requests, and discussions. Instead of scattering these across emails or chat, you can track them systematically alongside your repository.
Creating an Issue
- Click the Issues tab in the repository
- Click New issue
- Write a title and body:
Bug report example:
Title: Login button click shows blank white screen
Body:
## Symptoms
Clicking the "Login" button on the login page displays a white screen.
## Steps to Reproduce
1. Go to /login
2. Enter email and password
3. Click the "Login" button
4. White screen appears
## Expected Behavior
Should navigate to the main page
## Environment
- Browser: Chrome 120
- OS: Windows 11
- Click Submit new issue
A good issue title clearly describes the problem in one line.
Classifying with Labels
Labels let you quickly categorize and filter issues.
Default labels:
| Label | Meaning |
|-------|---------|
| bug | Bugs, malfunctions |
| enhancement | New feature requests |
| documentation | Documentation related |
| good first issue | Suitable for newcomers to contribute |
| help wanted | Issues that need help |
| question | Questions |
Click Labels on the right side of an issue → select the labels you want.
You can also create custom labels: Issues tab → Labels → New label.
Assigning with Assignees
Click Assignees on the right side of an issue → select the assignee.
Assigning someone:
- Sends them a notification
- Makes it clear who is handling the issue
- Lets you filter to see only your assigned issues
Linking Issues and PRs
Linking an issue to a PR automatically closes the issue when the PR is merged.
Use keywords in the PR description or body:
Closes #5
Fixes #12
Resolves #8
For example, if Issue #5 is "README update needed", writing Closes #5 in your PR description will auto-close the issue when the PR is merged.
"Why?" — Why an Issue Tracker Beats Email
When bugs are reported via email:
- Context gets lost (hard to find who said what and when)
- Multiple people report the same bug
- No way to tell if it has been resolved
With GitHub Issues:
- All discussion lives in one place per issue
- Duplicate issues are easy to spot and link
- A clear flow emerges: fix → merge PR → issue auto-closes
- Six months later, you can still trace "why did this change?"
If you want to contribute to open source, start by browsing the Issues tab. Issues labeled good first issue are well-suited for newcomers.
Deep Dive
Managing Deadlines with Milestones
You can group related issues and set goals with deadlines.
Issues tab → Milestones → New milestone
For example, create a "v1.0 Release" milestone and attach all issues that need to be resolved before launch. You can see the progress at a glance.
Setting Up Issue Templates
Adding issue templates to your repository ensures consistent formatting.
Settings → Features → Issues → Set up templates
You can create multiple templates such as bug reports and feature requests. This is commonly used in open-source projects.
- Create a new Issue in your repository. Title: "Add installation instructions to README". Set the label to
documentation. - Create a branch to resolve the issue and edit the README.
- When creating the PR, include
Closes #issue-numberin the description. - Merge the PR and confirm the issue is automatically closed.
Q1. What does the good first issue label mean on a GitHub Issue?
- A) This issue is the most important
- B) This issue is at a difficulty level suitable for newcomers to contribute
- C) This issue has already been resolved
- D) This issue needs urgent attention