GitHub Issues & Labels: complete project management

Updated March 2026 10 min read beginner to intermediate

Issues are the heartbeat of GitHub collaboration. Track bugs, request features, assign tasks, and organize work with labels, milestones, and templates. Learn how to manage projects like a pro.

What are Issues?

Issues are like digital sticky notes for your project. They help you track:

Bugs Features Questions Tasks

Each issue has a title, description, labels, assignees, and can be linked to milestones and projects.

Step 1: Create your first issue

Go to your repository → click the "Issues" tab → click the green "New issue" button.

Repository URL: https://github.com/username/repo/issues

Fill in:

Title: Short summary (e.g., "Fix login button not working")
Description: Detailed explanation, steps to reproduce, expected behavior

Example issue description:
## Bug Report
**Steps to reproduce:**
1. Go to login page
2. Enter valid credentials
3. Click "Sign In"
**Expected:** User gets redirected to dashboard
**Actual:** Nothing happens, console error shows 500

Click "Submit new issue". Congratulations, you've created your first issue!

Step 2: Labels – organize and categorize

Labels help you categorize issues. GitHub provides default labels, and you can create custom ones.

Default GitHub labels:

bug
Something isn't working

feature
New feature request

documentation
Improve documentation

question
Further information requested

enhancement
Improve existing feature

good first issue
Good for beginners

How to add labels:

On an issue page, click the "Labels" section in the right sidebar
Select one or more labels from the dropdown
To create custom labels: go to Issues → Labels → New label

Pro tip: Use labels like "priority-high", "needs-review", "in-progress" to track workflow status.

Step 3: Assignees – who is responsible?

Assign issues to team members to show who is working on it.

In the right sidebar of any issue, click "Assignees"
Select one or more people from your team
The assigned person will get a notification

Assigning helps avoid duplicate work and clarifies responsibility. You can also assign yourself to issues you're working on.

Step 4: Milestones – group issues by release or sprint

Milestones help you group related issues and track progress toward a goal (e.g., a software release).

Create a milestone:

Go to Issues → Milestones → New milestone
Set title, description, and due date
Add issues to the milestone from the issue page

Example milestone:
"v2.0 Release" – due: June 30, 2026
Contains: 8 open issues (3 bugs, 5 features)

Milestones show progress with a completion percentage bar. Great for sprint planning!

Step 5: Issue templates – standardize reports

Create templates so users and contributors follow a consistent format when filing issues.

How to create templates:

In your repository, create a folder: .github/ISSUE_TEMPLATE/ and add markdown files.


                .github/ISSUE_TEMPLATE/bug_report.md

                .github/ISSUE_TEMPLATE/feature_request.md

Example: bug_report.md
---
name: Bug report
about: Create a report to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---
**Describe the bug**
**To Reproduce**
**Expected behavior**
**Screenshots**
**Environment (please complete):**
- OS: [e.g. Windows]
- Browser [e.g. chrome, safari]

GitHub automatically shows these templates when someone clicks "New issue". Users can choose between bug report, feature request, etc.

Step 6: Search & filter – find what you need

GitHub has powerful search syntax to filter issues.

is:issue is:open
Open issues

label:bug
All bug issues

assignee:username
Assigned to someone

milestone:v2.0
Specific milestone

author:username
Created by someone

sort:updated-desc
Recently updated

Combine filters: is:issue label:bug assignee:@me milestone:v2.0

Step 7: Close and reopen issues

When an issue is resolved, close it. If it reappears, you can reopen.

At the bottom of an issue, click "Close issue" button
Closed issues are archived but can be reopened anytime
You can also close issues via commit messages: Fixes #123 in a commit will auto-close issue #123 when merged

git commit -m "Fix login button issue Fixes #42"

Pro tip: Use keywords like Closes #123, Fixes #456, or Resolves #789 in PR descriptions to auto-close issues when merged.

Issue best practices:
✅ Write clear, descriptive titles
✅ Use labels consistently
✅ Always assign someone responsible
✅ Link related issues and PRs
✅ Close issues when resolved
✅ Use templates for consistent reporting

Issues & Labels FAQ

What's the difference between Issues and Projects?

Issues are individual tasks, bugs, or discussions. Projects are Kanban-style boards that organize multiple issues into columns (To Do, In Progress, Done).

Can I assign multiple people to one issue?

Yes! You can assign multiple assignees to the same issue. Useful when a task requires collaboration.

How do I mention someone in an issue?

Type @username in the comment. That person will get a notification. Great for asking questions or assigning tasks.

What are "good first issues"?

A special label that indicates issues suitable for new contributors. Great for open source projects to welcome beginners.

Can I convert a discussion to an issue?

Yes! In GitHub Discussions, you can convert a discussion post into an issue. Click the three dots menu on a discussion and select "Convert to issue".

How do I link a pull request to an issue?

In the PR description, type Closes #123 or Fixes #123. GitHub will automatically link them and close the issue when the PR is merged.

What's the difference between a milestone and a project board?

Milestones group issues by a deadline or release version. Project boards track workflow status (Kanban). They complement each other.

Can I have issue templates for different languages?

Yes! You can create multiple template files. GitHub will show a dropdown with all available templates when creating a new issue.

How do I search for issues without a specific label?

Use -label:bug to exclude bugs. Example: is:open -label:bug shows all open issues that are not bugs.

Can I add emojis to issue titles and comments?

Yes! GitHub supports emojis. Type :smile: for 😄, or use the emoji picker in the comment toolbar.

How do I pin important issues?

On the Issues page, you can pin up to 3 important issues to the top of the list. Click the pin icon next to an issue.

What are issue dependencies?

You can mark an issue as blocking or blocked by another issue. Helps with task sequencing. Available on GitHub Enterprise and some public repos.

Previous: Forks & PRs Next: GitHub Projects

Issues are the foundation of great project management. Start tracking your work today!