GitHub Issues

What Are GitHub Issues?

GitHub Issues is a built-in issue tracking system for every repository. It's where your team records bugs, feature requests, questions, and tasks — keeping everything in one place alongside the code.

Issues are more than a to-do list. They're a communication hub where requirements are clarified, implementation is discussed, and decisions are documented. Long after code is merged, issues preserve the context of why something was built a certain way.

Creating an Issue

1. Go to the Issues tab in your repository
2. Click New issue
3. Give it a clear, descriptive title
4. Write a description (see format below)
5. Set labels, assignees, and milestone on the right sidebar
6. Click Submit new issue

Writing Good Issues

A clear issue template:

## Description
Brief description of the bug or feature.

## Steps to Reproduce (for bugs)
1. Go to /login
2. Submit form with empty email
3. See error

## Expected Behavior
Should show a validation error "Email is required"

## Actual Behavior
Form submits successfully with empty email, server returns 500

## Environment
- OS: macOS 14
- Browser: Chrome 122
- Version: 2.1.4

## Additional Context
Screenshot or logs here

For feature requests:

## Problem
Describe the problem this feature solves.

## Proposed Solution
How you think it should work.

## Alternatives Considered
Other approaches you thought about.

Labels

Labels categorize and filter issues. GitHub creates default labels; add your own in Settings → Labels.

Default labels:

Label	Use for
bug	Something isn't working
enhancement	New feature or request
documentation	Docs improvements
good first issue	Good for newcomers
help wanted	Extra attention needed
question	More information requested
wontfix	This will not be worked on
duplicate	Issue already exists

Custom labels (common team additions):

Label	Use for
priority: high	Needs to be done ASAP
priority: low	Nice to have
blocked	Waiting on something else
in review	PR is open, under review
backend / frontend	Area of codebase

Assignees and Milestones

• Assignees — who is responsible for fixing this issue
• Milestone — groups issues into a sprint, version, or deadline

Create a milestone for your upcoming release (e.g., v2.0.0 or Sprint 5) and assign issues to it. The milestone page shows your progress as a percentage of closed issues.

Linking Issues to Pull Requests

When you open a PR that resolves an issue, link them using keywords in the PR description:

Closes #42
Fixes #17
Resolves #103

When the PR is merged into the default branch, the linked issue closes automatically. This is a massive time saver — no manual issue closing.

You can also reference issues without auto-closing:

Related to #55
See #88 for context

Mentioning Issues in Commits

Reference issues in commit messages for traceability:

git commit -m "Add email validation to login form (#42)"
git commit -m "Fix null pointer in user serializer, refs #67"

The issue gets a timeline entry showing which commit mentioned it, creating a permanent link between the work and the requirement.

Issue Templates

For teams, standardize issue creation with templates. Create files in .github/ISSUE_TEMPLATE/:

.github/ISSUE_TEMPLATE/bug_report.md

---
name: Bug Report
about: Report a bug to help us improve
labels: bug
---

## Description
<!-- Clear description of the bug -->

## Steps to Reproduce
1.
2.
3.

## Expected vs Actual Behavior
**Expected:**
**Actual:**

## Environment
- OS:
- Browser:
- Version:

.github/ISSUE_TEMPLATE/feature_request.md

---
name: Feature Request
about: Suggest a new feature or improvement
labels: enhancement
---

## Problem
<!-- What problem does this solve? -->

## Proposed Solution
<!-- How should it work? -->

Now when anyone clicks "New issue," they choose from your templates.

Filtering and Searching Issues

The Issues tab has powerful filters:

is:open                    # all open issues
is:closed                  # all closed issues
is:open label:bug          # open bugs
assignee:mrizwanashiq      # assigned to you
milestone:"Sprint 5"       # in a specific milestone
no:assignee                # unassigned issues
mentions:me                # issues mentioning you

GitHub Projects (Kanban Board)

For visual project management, link issues to a GitHub Project:

1. Go to Projects tab → New project
2. Choose a template (Board, Table, or Roadmap)
3. Add your issues as cards

Issues automatically update their project status when labeled or closed, giving you a real-time Kanban board without any extra tooling.

Workflow: Issue → Branch → PR → Merge

The complete development workflow:

1. Issue created: "Add dark mode toggle" (#55)

2. Developer creates a branch:
   git checkout -b feature/dark-mode-#55

3. Developer commits work:
   git commit -m "Add dark mode toggle to settings page (#55)"

4. PR opened with description:
   "Closes #55 — adds theme toggle to user preferences"

5. PR reviewed and merged → Issue #55 closes automatically

6. Branch deleted

Every piece of work is traceable from requirement (issue) to implementation (PR) to merged code.