GitHub Issues Mastery: The Complete Guide to Tracking Bugs, Features, Tasks & Project Work

When a software project starts growing, managing everything becomes difficult.

You may have:

• Bugs that need fixing

• New features to build

• Improvements to make

• Documentation to update

• Tasks assigned to different developers

• Problems reported by users

If all of these are tracked through messages or notes, things can quickly become confusing.

This is where GitHub Issues becomes extremely useful.

GitHub Issues provides a structured way to track bugs, feature requests, tasks, improvements, and other pieces of work inside a repository.

In this article, you'll learn how GitHub Issues work, how to create and manage them, labels, milestones, assignments, Issue templates, linking Issues with Pull Requests, and how developers use Issues in real-world projects.

---

What Are GitHub Issues?

A GitHub Issue is a way to track a specific piece of work, problem, idea, or task in a repository.

For example:

Bug:
Login button doesn't work

or:

Feature:
Add dark mode

or:

Task:
Update project documentation

An Issue gives the team a central place to discuss and track that work.

---

GitHub Issues in Simple Words

Think of an Issue as a digital task card for your software project.

For example:

Project
   ↓
Issue
   ↓
Problem / Task
   ↓
Discussion
   ↓
Developer
   ↓
Fix
   ↓
Pull Request

Instead of remembering tasks manually, the project keeps them inside GitHub.

---

Why Do Developers Use GitHub Issues?

Imagine a project has these problems:

1. Login is broken
2. Add search feature
3. Improve homepage
4. Update README
5. Fix mobile layout

Without a tracking system, developers may forget tasks.

With GitHub Issues:

Issue #101 → Login bug
Issue #102 → Search feature
Issue #103 → Homepage improvement
Issue #104 → README update
Issue #105 → Mobile layout

Every task has its own place.

---

What Can You Track With Issues?

GitHub Issues can be used for many types of work.

Bugs

Login fails after password reset.

Features

Add Google authentication.

Improvements

Improve page loading speed.

Tasks

Update dependencies.

Documentation

Add API usage examples.

---

GitHub Issue Structure

A typical Issue can contain:

Title
Description
Assignees
Labels
Milestone
Comments
References
Linked Pull Requests

For example:

Issue #125

Title:
Fix login validation

Description:
Users can submit an empty password field.

Assignee:
@developer

Labels:
bug, priority-high

Milestone:
Version 2.0

---

Creating a GitHub Issue

The general process is simple.

Step 1: Open Your Repository

Go to your GitHub repository.

Step 2: Open Issues

Select:

Issues

Step 3: Create a New Issue

Choose the option to create a new Issue.

Step 4: Add a Title

For example:

Fix login button validation

Step 5: Describe the Problem

Explain what happened and what you expect.

Step 6: Add Labels

For example:

bug

Step 7: Assign Someone

Choose the developer responsible for the work.

Step 8: Submit the Issue

The Issue is now available for the team to track.

GitHub's interface may change over time, but the basic workflow remains similar.

---

Writing a Good Issue Title

A good title should immediately explain the problem or task.

Bad:

Login problem

Better:

Login fails when users enter an incorrect password

For a feature:

Bad:

Dark mode

Better:

Add dark mode to the user dashboard

A clear title saves time.

---

Writing a Good Issue Description

A useful bug report should provide enough information for someone else to understand and reproduce the problem.

A good structure is:

## Description

Explain the problem.

## Steps to Reproduce

1. Open login page.
2. Enter username.
3. Enter incorrect password.
4. Click Login.

## Expected Behavior

An error message should appear.

## Actual Behavior

The page freezes.

## Environment

Browser:
Chrome

Operating System:
Windows

This gives developers useful context.

---

Issue Templates

If many users create Issues, the reports may have inconsistent formats.

One user might provide detailed information.

Another might simply write:

It doesn't work.

Issue templates help solve this problem.

A template can automatically provide sections such as:

Description

Steps to Reproduce

Expected Behavior

Actual Behavior

Screenshots

Environment

This encourages users to submit better reports.

---

Bug Report Template

A project might provide a bug-report template like:

## Bug Description

Describe the bug.

## Steps to Reproduce

1.
2.
3.

## Expected Behavior

What should happen?

## Actual Behavior

What actually happens?

## Screenshots

Add screenshots if applicable.

## Environment

OS:
Browser:
Version:

This makes bug reports easier to investigate.

---

Feature Request Template

A feature request template might contain:

## Feature

Describe the feature.

## Problem

What problem does this solve?

## Proposed Solution

How should it work?

## Alternatives

What alternatives have you considered?

This helps maintainers understand why the feature is needed.

---

GitHub Issue Labels

Labels are one of the most useful Issue features.

They help categorize Issues.

Examples:

bug
feature
documentation
enhancement
good first issue
help wanted
priority-high

A project might have:

Issue #52

with:

bug
priority-high

This immediately tells developers what type of work it is.

---

Why Are Labels Important?

Imagine a project has 500 Issues.

Without labels:

Issue #1
Issue #2
Issue #3
...
Issue #500

Finding relevant Issues becomes difficult.

With labels:

bug → 120 Issues
feature → 80 Issues
documentation → 30 Issues
good first issue → 25 Issues

Developers can filter and organize work more effectively.

---

Common GitHub Labels

Some commonly used labels include:

bug

Used for problems in the software.

enhancement

Used for improvements or new functionality.

documentation

Used for documentation work.

good first issue

Used for tasks suitable for newcomers.

help wanted

Indicates that maintainers would appreciate community assistance.

duplicate

Indicates that the Issue has already been reported.

question

Used when the Issue is primarily a question, although GitHub Discussions may be more appropriate for general questions.

---

Priority Labels

Teams may also create priority labels.

For example:

priority-critical
priority-high
priority-medium
priority-low

Then Issues can be organized according to importance.

Example:

Issue #45
Fix payment failure

Labels:
bug
priority-critical

---

Assigning Issues

An Issue can be assigned to one or more people, depending on the repository's setup and GitHub's current capabilities.

For example:

Issue #75
Add payment validation

Assigned to:
@rahul

Now Rahul knows that he is responsible for the task.

---

Why Assign Issues?

Assignments provide clear ownership.

Without assignment:

Everyone thinks:
"Someone else will fix it."

With assignment:

Issue
 ↓
Assigned Developer
 ↓
Responsible for the Work

This reduces confusion.

---

Milestones

A milestone groups Issues toward a larger goal, such as a release or project objective.

For example:

Milestone:
Version 2.0

could contain:

Issue #101 → Login
Issue #102 → Dashboard
Issue #103 → Payment
Issue #104 → Documentation

Once the Issues are completed, the milestone progresses toward completion.

---

Milestone Example

Imagine you're developing:

Student Management System

You could create:

Milestone: Version 1.0

with:

Issue #1 → Login
Issue #2 → Student registration
Issue #3 → Attendance
Issue #4 → Reports
Issue #5 → Documentation

This provides a high-level view of the release.

---

Issues and Projects

GitHub also provides Projects, which can provide a broader planning and project-management layer.

A typical workflow might look like:

Issue
  ↓
GitHub Project
  ↓
To Do
  ↓
In Progress
  ↓
Review
  ↓
Done

Projects can organize Issues into different views and workflows.

---

Issues vs Projects

These are not the same thing.

Issues	Projects
Track individual work	Organize work at a broader level
Bug tracking	Project planning
Feature requests	Workflow management
Tasks	Views and planning
Discussions around work	Track many Issues together

A simple way to remember:

Issue = What needs to be done?

Project = How are we organizing the work?

---

Linking Issues to Pull Requests

This is one of the most powerful GitHub workflows.

Suppose you have:

Issue #25
Fix login validation

A developer creates a Pull Request to fix it.

The Pull Request can reference the Issue.

For example, a Pull Request description can contain:

Fixes #25

Depending on the repository's workflow and GitHub's supported closing keywords, linking the PR to the Issue can cause the Issue to close automatically when the Pull Request is merged.

The workflow becomes:

Issue #25
    ↓
Developer Works
    ↓
Pull Request
    ↓
Code Review
    ↓
Merge
    ↓
Issue Closed

This connects planning directly to development.

---

Common Closing Keywords

GitHub supports keywords that can automatically close linked Issues when the relevant Pull Request is merged into the default branch, subject to the repository workflow.

Examples include:

Fixes #25
Closes #25
Resolves #25

For example:

Fixes #25

means the Pull Request addresses Issue #25.

---

Linking Without Automatically Closing

Sometimes you want to reference an Issue without closing it automatically.

You can simply reference it:

#25

or use wording such as:

Related to #25

This creates a connection without necessarily indicating that the Issue should close when the PR merges.

---

Issues and Commits

Issues can also be referenced from commit messages.

For example:

git commit -m "Fix login validation #25"

This creates a reference to the Issue.

Developers can then follow the relationship between:

Issue
 ↓
Commit
 ↓
Pull Request

---

Issue References

You can reference another Issue using:

#25

For example:

This problem is related to #25.

GitHub recognizes the reference and creates a link.

---

Cross-Repository Issues

GitHub also supports references to Issues in other repositories when using the appropriate repository reference syntax and permissions.

This can be useful for organizations with multiple repositories.

For example, one repository may depend on work happening in another repository.

---

Closing an Issue

An Issue can be closed when the work is completed or the conversation no longer requires active tracking.

For example:

Issue
 ↓
Development
 ↓
Testing
 ↓
Completed
 ↓
Closed

Closing an Issue doesn't necessarily mean the Issue was fixed.

It may also be closed because it is:

• Duplicate

• No longer relevant

• Invalid

• Superseded

• Completed

---

Reopening an Issue

If a problem returns, an authorized user may be able to reopen the Issue.

For example:

Issue
 ↓
Closed
 ↓
Bug Appears Again
 ↓
Reopened

This keeps the history of the problem in one place.

---

Duplicate Issues

Sometimes multiple users report the same bug.

For example:

Issue #10
Login crashes

Issue #25
Login crashes after password reset

Issue #31
Application crashes during login

If they describe the same underlying problem, maintainers can mark later reports as duplicates and keep the original Issue as the primary tracking item.

---

Good First Issue

If you want new contributors to participate, you can label suitable tasks:

good first issue

For example:

Issue #120
Improve README grammar

Label:
good first issue

A beginner contributor can search for these Issues and make their first contribution.

---

Help Wanted

Another useful label is:

help wanted

It tells the community that maintainers would appreciate contributions.

For example:

Issue:
Add documentation for API authentication

Labels:
documentation
help wanted

---

GitHub Issues for Open Source

Issues are extremely important in open-source projects.

A typical workflow is:

User Finds Problem
       ↓
Creates Issue
       ↓
Maintainer Investigates
       ↓
Developer Works on Fix
       ↓
Pull Request
       ↓
Code Review
       ↓
Merge
       ↓
Issue Closed

This allows users and developers to collaborate publicly.

---

Example: Real-World Development Workflow

Imagine you're building an ecommerce application.

A customer reports:

"Checkout fails when using a discount code."

You create:

Issue #245

Title:
Checkout fails when applying discount codes

Add:

Labels:
bug
priority-high

Assign:

@backend-developer

Then the developer creates a Pull Request:

Fixes #245

After review and merging:

Issue #245
     ↓
Resolved
     ↓
Closed

Everything is connected.

---

Issue Comments

Issues are also conversation spaces.

Developers can add comments such as:

I reproduced the problem.

The issue appears to happen only on mobile devices.

Another developer might respond:

I've identified the cause and am working on a fix.

This creates a record of the investigation.

---

Issue Mentions

You can mention someone using:

@username

For example:

@rahul Can you investigate this API issue?

This can bring the appropriate person into the conversation.

---

Screenshots and Files

Issue descriptions can include supporting material such as:

• Screenshots

• Logs

• Error messages

• Videos

• Documents

This can make bug reports much easier to understand.

---

GitHub Issue Forms

GitHub also supports Issue Forms, which can provide structured forms for collecting information.

Instead of asking users to manually format a bug report, a project can provide fields such as:

Bug Description
Steps to Reproduce
Expected Result
Actual Result
Operating System
Version

This is especially useful for larger projects.

---

Issue Forms vs Templates

Both help standardize Issues.

Issue Template

Provides a predefined description structure.

Issue Form

Provides structured fields that users can fill in.

For example:

Issue Form

Bug:
[________________]

Steps:
[________________]

Version:
[________________]

This can make reports more consistent.

---

Security Issues Are Different

Not every problem should be reported publicly as a normal Issue.

Security vulnerabilities may need a private reporting process instead.

For sensitive security problems, use the repository's supported security reporting mechanism rather than publicly exposing vulnerability details.

We'll cover GitHub Security in a dedicated article later in this series.

---

GitHub Issues and Automation

Issues can also work with automation.

For example:

New Issue
   ↓
Label Automatically
   ↓
Assign Team
   ↓
Add to Project

This can reduce repetitive manual work.

Automation becomes particularly useful when a repository receives many Issues.

---

Issue Workflow for a Professional Team

A professional development process might look like:

Problem Identified
       ↓
Create Issue
       ↓
Add Labels
       ↓
Assign Developer
       ↓
Add to Milestone / Project
       ↓
Development
       ↓
Pull Request
       ↓
Code Review
       ↓
Merge
       ↓
Issue Closed

This creates traceability from a problem to its final solution.

---

Best Practices for GitHub Issues

Write Clear Titles

Make the purpose obvious.

Instead of:

Problem

write:

Search crashes when query contains special characters

---

Provide Reproduction Steps

For bugs, explain exactly how the problem can be reproduced.

---

Use Labels

Categorize Issues properly.

---

Assign Ownership

Make sure someone is responsible for the work.

---

Use Milestones

Group Issues belonging to the same release or objective.

---

Link Pull Requests

Connect development work back to the Issue.

---

Close Completed Issues

Don't leave finished work unnecessarily open.

---

Common Beginner Mistakes

Creating Issues Without Enough Information

Bad:

It doesn't work.

Better:

The login page returns a 500 error after submitting
an incorrect password.

---

Using Issues for General Conversations

GitHub Discussions may be more suitable for general community conversations.

---

Not Using Labels

Without labels, large Issue lists become difficult to manage.

---

Not Assigning Work

Unassigned Issues can easily be forgotten.

---

Creating Duplicate Issues

Search existing Issues before creating a new one.

---

Closing Issues Too Early

Make sure the problem is actually resolved before closing it.

---

Example Issue

Here's a complete example:

Issue #154

Title:
Checkout crashes when applying an expired coupon

Description:

## Bug Description
The checkout page crashes when a user applies an expired coupon.

## Steps to Reproduce
1. Add a product to the cart.
2. Go to checkout.
3. Enter an expired coupon.
4. Click Apply.

## Expected Behavior
An error message should explain that the coupon has expired.

## Actual Behavior
The checkout page crashes.

## Environment
Browser: Chrome
OS: Windows
Version: 2.4.1

Labels:
bug
priority-high

Assignee:
@developer

Milestone:
Version 2.5

This is a high-quality Issue because it gives developers enough information to investigate the problem.

---

Issues vs Discussions vs Pull Requests

These three GitHub features are easy to confuse.

Feature	Main Purpose
Discussions	Conversations and community questions
Issues	Bugs, tasks, features and work tracking
Pull Requests	Proposing and reviewing code changes

A simple workflow is:

Discussion
    ↓
Idea / Problem
    ↓
Issue
    ↓
Development
    ↓
Pull Request
    ↓
Review
    ↓
Merge

Not every project follows this exact sequence, but it is a useful model.

---

Why GitHub Issues Matter

GitHub Issues aren't just a list of bugs.

They can become the central connection between:

Users
 ↓
Problems
 ↓
Developers
 ↓
Tasks
 ↓
Code
 ↓
Pull Requests
 ↓
Releases

This gives a project a clear history of why changes were made.

---

Frequently Asked Questions

What are GitHub Issues?

GitHub Issues are tools for tracking bugs, features, tasks, improvements, and other work in a repository.

Are GitHub Issues free?

GitHub provides Issues as part of its repository collaboration features, with availability depending on the repository/account context.

Can I assign an Issue to a developer?

Yes, if you have the necessary permissions.

What are Issue labels?

Labels categorize Issues and make them easier to filter and organize.

What is a milestone?

A milestone groups Issues around a larger goal, such as a release.

Can an Issue be linked to a Pull Request?

Yes.

Can an Issue close automatically?

Yes. Using supported closing keywords in a Pull Request can automatically close linked Issues when the PR is merged into the appropriate branch.

Are Issues only for bugs?

No. They can track features, tasks, documentation, improvements, and many other types of work.

Should I use Discussions or Issues for questions?

General questions and community conversations are often better suited to Discussions, while actionable development work generally belongs in Issues.

---

Summary

GitHub Issues provide a structured way to manage software development work.

You can use Issues to:

• Report bugs

• Request features

• Track tasks

• Assign developers

• Add labels

• Organize milestones

• Discuss problems

• Link Pull Requests

• Track work from discovery to completion

The basic workflow is:

Issue
  ↓
Assign
  ↓
Develop
  ↓
Pull Request
  ↓
Review
  ↓
Merge
  ↓
Close Issue

Once you understand Issues, you can start using GitHub not just as a place to store code, but as a complete platform for managing software development.