GitHub Issues: Tasks, Bugs, and Ideas in One Place 🐛

GitHub Issues is the built-in task tracker in every repository. It’s where bugs are discussed, features are requested, and team work is coordinated.

What Is an Issue?

An issue is a discussion thread tied to a repository. It can be:

• 🐛 Bug — “the login button doesn’t work on mobile”
• 💡 Feature idea — “I’d like a dark theme”
• ❓ Question — “how do I configure environment variables correctly?”
• 📋 Task — “need to add a route for Chicago”
• 🚀 Improvement — “the registration form is too slow”

How to Find Issues

Go to any repository → Issues tab.

Filters

is:open   — open (in progress)
is:closed — closed (resolved)
label:bug — bugs only
label:help-wanted — looking for help
label:good-first-issue — good tasks for beginners ← your go-to!
author:username — issues by a specific user

How to Create an Issue

When you found a bug

1. Open the Issues tab → New issue
2. Write a clear title: Login button doesn't work on iOS
3. In the description include:

## What happens
Clicking the "Login" button on iPhone does nothing.

## How to reproduce
1. Open the site on iPhone (iOS 17.2)
2. Click "Login"
3. Nothing happens, the page doesn't change

## Expected behavior
Navigate to the login page or open the login form.

## Environment
- Device: iPhone 13
- Browser: Safari 17
- App version: 2.3.1

When you want to suggest an improvement

## Idea
Add dark theme support.

## Why
30% of users have dark mode enabled in their OS settings,
our site doesn't support it and looks uncomfortable.

## Proposal
Use CSS `prefers-color-scheme` for auto-detection
and add a manual toggle in settings.

How to Pick Up an Issue (Open Source)

Step 1: Find a suitable task

Look for Issues with labels:
- good-first-issue — specifically for newcomers
- help-wanted — the team is looking for help
- beginner-friendly — friendly tasks

Step 2: Say you’re taking it on

Before you start — leave a comment:

Hi! I'd like to take this task. Planning to finish by end of the week.
Am I understanding correctly that I need to add a route for [city]?

This is important because:
- You don’t waste time if someone else is already working on it
- The team knows the task is being handled
- The maintainer can provide clarification

Step 3: Do the work and create a PR

In the PR description, reference the Issue:

Closes #42

When the PR is merged, this will automatically close Issue #42.

Keywords to Close an Issue

In a PR description or comment you can write:

Closes #42
Fixes #42
Resolves #42

GitHub will automatically close the Issue when the PR is merged into main.

Labels

Labels are colored tags for classifying Issues:

Assignees

An assignee is the person responsible for resolving the Issue.

In a team project: the team lead assigns Issues to specific developers.
In open source: you can ask to be assigned, or the maintainer will do it.

Milestones

A milestone is a group of Issues tied to a common goal or deadline:

Milestone: v2.0 (deadline: June 1)
├── Issue #41: Dark theme
├── Issue #42: Mobile version
└── Issue #43: API documentation

Helps track progress toward a release.

Issues and Projects

GitHub Projects is a task board (like Trello) built into GitHub.
Issues automatically show up on the board.

Backlog → In Progress → Review → Done
  #41        #42          #43      #44

Issue Etiquette

Search before creating

Check that a similar Issue doesn’t already exist. Duplicates are a common problem in popular projects.

Issues → filter → enter keywords

One Issue = one problem

❌ Bad: "bugs in the mobile version and bad navigation and..."

✅ Good:
Issue #50: login button doesn't work on iOS
Issue #51: bad navigation on mobile

Be polite

Maintainers are often volunteers working on the project in their free time.

❌ "Why hasn't this been fixed yet?! It's been broken for a year!"

✅ "Hey! I ran into this bug, just wanted to check — is this a known issue?
   Happy to help with a fix if you can point me in the right direction."

Issues in a Team Project

In a closed team project, Issues serve as your task tracker:

1. The team lead creates Issues for each task
2. Assigns Issues to developers
3. Developers create branches and PRs referencing the Issues
4. PR is merged → Issue closes automatically

This creates full traceability: from the Issue you can see which PR resolved it,
from the PR you can see which task it addressed.