GitHub Issues and Project Management

What are GitHub Issues?

GitHub Issues is a built-in tracking system for every GitHub repository. Issues are used to report bugs, request new features, ask questions, and plan work. Every issue has a title, description, comments section, and can be assigned to team members, labeled, and linked to pull requests.

Issues serve as the central communication hub for a project — both for internal teams and for open-source communities where users can report problems directly.

Creating an Issue

1. Open the GitHub repository
2. Click the "Issues" tab
3. Click "New issue"
4. Fill in:
   • Title — Clear, specific summary (e.g., "Login button not working on mobile Safari")
   • Description — Detailed explanation with steps to reproduce, expected behavior, and actual behavior
5. Click "Submit new issue"

Writing a Good Issue

A well-written issue gets resolved faster. For bug reports, include:

## Bug Description
The login button does not respond when tapped on iPhone 14 using Safari.

## Steps to Reproduce
1. Open the website on Safari mobile
2. Enter valid email and password
3. Tap the "Login" button
4. Nothing happens — no error, no redirect

## Expected Behavior
The user should be redirected to the dashboard after login.

## Actual Behavior
The button appears to receive the tap but nothing happens.

## Environment
- Device: iPhone 14
- OS: iOS 17.0
- Browser: Safari 17

Issue Components

Labels

Labels are colored tags that categorize issues. Default labels include:

Custom labels can also be created (e.g., priority: high, frontend, backend).

Assignees

Assign an issue to one or more team members responsible for resolving it.

Milestones

A milestone groups issues and pull requests toward a specific goal or deadline (e.g., "Version 2.0 Release" or "Q4 Sprint"). Progress is shown as a percentage of closed issues.

Projects

Issues can be linked to a GitHub Project board for visual task management.

Closing Issues via Commit Messages

Issues can be automatically closed when a pull request is merged by using special keywords in the PR description or commit message:

Fixes #42
Closes #15
Resolves #8

When the pull request is merged into the default branch, GitHub automatically closes all referenced issues. This links code changes directly to the work items they address.

Issue Templates

Issue templates pre-fill forms so reporters provide consistent, complete information. They are stored in .github/ISSUE_TEMPLATE/:

# .github/ISSUE_TEMPLATE/bug_report.md

---
name: Bug Report
about: Report a bug to help the project improve
title: "[BUG] "
labels: bug
assignees: ''
---

## Describe the Bug
A clear description of the bug.

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What should happen.

## Screenshots
If applicable, add screenshots.

## Environment
- OS: [e.g., Windows 11]
- Browser: [e.g., Chrome 118]

GitHub Projects — Kanban Board for Tasks

GitHub Projects provides a visual project management board similar to Trello. Issues and pull requests can be organized into columns like "To Do", "In Progress", and "Done".

Creating a Project

1. Go to the repository or organization
2. Click the "Projects" tab
3. Click "New project"
4. Choose a template (Board, Table, Roadmap)
5. Add issues and PRs to the board

Board View

┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   Backlog   │  │   To Do     │  │ In Progress │  │    Done     │
├─────────────┤  ├─────────────┤  ├─────────────┤  ├─────────────┤
│ Issue #12   │  │ Issue #7    │  │ Issue #3    │  │ Issue #1    │
│ Issue #15   │  │ Issue #9    │  │ PR #22      │  │ Issue #2    │
│ Issue #20   │  │             │  │             │  │ Issue #4    │
└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘

Linking Issues to Pull Requests

In a pull request description, reference related issues:

• Fixes #42 — Closes issue #42 when the PR is merged
• Related to #15 — Links without closing
• See #8 — Creates a reference link

Mentions and Notifications

In any issue or PR comment, people can be mentioned using the @username syntax. They receive a notification. Teams can also be mentioned using @org/team-name.

Searching and Filtering Issues

The Issues tab provides powerful filtering. Useful search filters:

is:open is:issue                  # All open issues
is:open label:bug                 # Open bugs
assignee:ravikumar                # Issues assigned to ravikumar
is:open milestone:"Version 2.0"   # Open issues for a specific milestone
author:priya                      # Issues created by priya
is:closed                         # All closed issues

GitHub Discussions

For conversations that are not bugs or tasks — like ideas, Q&A, or general feedback — GitHub Discussions provides a forum-like space separate from Issues. It is ideal for open-source communities.

Summary

GitHub Issues is a full-featured task tracking system built into every repository. Issues can be labeled, assigned, and organized into milestones and project boards. Using keywords like Fixes #42 in pull requests automatically closes issues on merge. Issue templates ensure bug reports are complete and consistent. Together with GitHub Projects boards, Issues provide everything needed to manage work from idea to completion.