GitHub Issues - Task & Bug Management

GitHub Issues is a feature for recording and tracking tasks, bugs, questions, and ideas in a project. Think of it as a shared to-do list where your team can see “what needs to be done” and “what problems exist” in one place.

What Are Issues?

Issues is the built-in ticket management system in a GitHub repository. Each issue corresponds to one task or problem.

Common uses include:

Reporting a bug: “The login button doesn’t work”
Logging a feature request: “I want to add a search feature”
Creating a work task: “Research how to implement X”
Asking the team: “Is this the right architecture for this?”

Why Use Issues?

The main reason to use Issues is to prevent work from falling through the cracks and ensure everyone on the team is working from the same information.

Conversations in email or chat disappear over time, but anything recorded in Issues can be searched and found later. You can also clearly show who is responsible for something and which release it targets.

Creating an Issue

Open the “Issues” tab in your repository and click “New issue”.

Field	Description	Example
Title	A concise summary of the problem or task	`Login button doesn't work in certain browsers`
Description	Detailed information, reproduction steps, expected behavior	See templates below
Labels	Tags that classify the type of issue	`bug`, `enhancement`, etc.
Assignees	The person responsible for this issue	`@yamada`
Milestone	Link to a release version or deadline	`v1.2.0`
Projects	The project board this issue belongs to	`Sprint 3`

Writing a Good Title

A good title makes it immediately clear “what the problem is” or “what needs to be done”.

Rating	Example	Why
Good	`Login form cannot be submitted on iOS Safari`	OS, browser, and symptom are all clear
Good	`Add user search feature`	The task is clear
Bad	`Bug`	Doesn’t explain what bug
Bad	`Fix`	Doesn’t explain what to fix

Using Labels

Labels are color-coded tags that classify issues. When scanning a list, they let you see at a glance what kind of issues exist.

GitHub’s Default Labels

Label	Meaning
`bug`	Something isn’t working
`enhancement`	A new feature or improvement
`documentation`	Documentation fixes or additions
`good first issue`	A good issue for newcomers to tackle
`help wanted`	Extra attention or collaboration is needed
`question`	A question or discussion
`wontfix`	This won’t be worked on
`duplicate`	A duplicate of another issue
`invalid`	An invalid or unconfirmed report

Creating Custom Labels

You can create custom labels that fit your team’s workflow. Here are some common examples:

Custom Label	Meaning
`priority: high`	High priority
`priority: low`	Low priority
`area: frontend`	Frontend-related
`area: backend`	Backend-related
`status: blocked`	Blocked waiting on another issue
`type: refactor`	Code refactoring

Go to “Issues” → “Labels” → “New label” to create one.

Using Milestones

A milestone groups issues together toward a specific release or deadline.

For example, create a milestone called v1.0.0 Release and attach all the issues that need to be resolved for that version. GitHub will display your progress as a percentage.

How to Create a Milestone

Go to “Issues” → “Milestones”
Click “New milestone”
Enter a title (e.g. v1.0.0), a due date, and a description
Click “Create milestone”

Closing an Issue

Issues can be closed in two ways:

Close Manually

Click the “Close issue” button at the bottom of the issue page.

Auto-close When a PR Is Merged

If you include one of the following keywords followed by an issue number in the PR title or body, the issue will automatically close the moment the PR is merged.

Closes #123
Fixes #456
Resolves #789

For example, writing Closes #42 in a PR description will automatically close Issue #42 when the PR merges. This removes the need to manually close issues after finishing work.

Creating Issue Templates

If you want bug reports or feature requests to follow a consistent format, you can create templates. Templates help reporters include all the necessary information.

Bug Report Template Example

Create .github/ISSUE_TEMPLATE/bug_report.md:

---
name: Bug Report
about: Use this template to report a bug
labels: bug
---

## What Is Happening

<!-- Briefly describe the problem -->

## Steps to Reproduce

1. Open the page at ...
2. Click ...
3. Error occurs

## Expected Behavior

<!-- What should happen instead? -->

## Actual Behavior

<!-- What actually happens? -->

## Environment

- OS: macOS 14.x / Windows 11 / Ubuntu 22.04
- Browser: Chrome 120 / Firefox 121 / Safari 17
- App version: v1.2.3

## Screenshots

<!-- Attach images if available -->

Feature Request Template Example

Create .github/ISSUE_TEMPLATE/feature_request.md:

---
name: Feature Request
about: Use this template to propose a new feature or improvement
labels: enhancement
---

## Feature Proposal

<!-- Describe the feature or improvement you're proposing -->

## Problem This Solves

<!-- Explain what problem you're running into without this feature -->

## Proposed Solution

<!-- If you have ideas on how to implement it, share them here -->

## Alternatives

<!-- Are there other ways to solve the same problem? -->

Real-world Use Cases

Use Case 1: Bug Reporting and Tracking

QA team finds a bug → Creates an issue with the bug label
Assign the responsible engineer (add to Assignees)
Engineer creates a fix branch and writes Fixes #42 in the PR description
When the PR merges, Issue #42 is automatically closed
QA team runs a regression test to confirm the fix

Use Case 2: Sprint Task Management

Create a Sprint 5 milestone at the start of a sprint
Link the sprint’s issues to the milestone
Visualize progress on a kanban board using Projects (GitHub Projects)
Check the milestone close rate at the end of the sprint

Use Case 3: Contributing to Open Source

Find an issue labeled good first issue
Leave a comment saying you’ll work on it
Fork the repo, create a branch, and make your fix
Send a PR with Closes #<issue number> in the description

Frequently Asked Questions

Q. Can anyone create an issue?

In public repositories, anyone with a GitHub account can create issues. Private repositories require access to the repository.

Q. How much should I write in the issue description?

For bug reports, the minimum is: reproduction steps, expected behavior, actual behavior, and environment info. Screenshots or videos make it even clearer.

Q. I have too many issues and it’s getting hard to manage.

Use labels and milestones to organize them. It also helps to periodically review old issues and close ones you won’t address by adding the wontfix label.

Q. I wrote `Closes #123` but the issue didn’t close.

Auto-close only triggers when the PR is merged into main (or the default branch). It won’t fire when merging into other branches. Also check for typos in the keyword (Close vs Closes) and make sure the issue number is correct.

Q. A duplicate issue was created. What should I do?

Add the duplicate label to one of them, leave a comment like “This is a duplicate of Issue #XX”, and close it. Include a link to the original issue so anyone who finds it later knows where to go.