Skip to main content

Managing Issues and Projects on GitHub

Now that you're comfortable with Git fundamentals and basic GitHub collaboration, let's explore how GitHub helps organize and track work beyond just code. In this lesson, you'll learn to use GitHub's project management features to coordinate team efforts and track progress systematically.

Learning Goals:

  • Create and manage GitHub Issues to track bugs and feature requests
  • Organize work using labels, milestones, and assignees
  • Use GitHub Projects for visual project management
  • Understand how issues integrate with pull requests and development workflows

Understanding GitHub Issues​

GitHub Issues are the foundation of project management on GitHub. They serve as todo items, bug reports, feature requests, or discussion threads that help teams track work that needs to be done.

Creating Your First Issue​

Navigate to any repository and click the "Issues" tab, then "New issue". Here's what a well-structured issue might look like:

Sample Bug Report Issue
## Bug Description
The login button becomes unresponsive after three failed login attempts.

## Steps to Reproduce
1. Navigate to the login page
2. Enter incorrect credentials three times
3. Click the login button - it no longer responds

## Expected Behavior
The button should display an error message and remain clickable.

## Environment
- Browser: Chrome 91
- OS: Windows 10
tip

Always include clear reproduction steps in bug reports. This helps developers quickly identify and fix the problem without guessing what you experienced.

Organizing Issues with Labels and Milestones​

Using Labels Effectively​

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

Common Label Categories
# Type labels
bug | enhancement | documentation | question

# Priority labels
high priority | medium priority | low priority

# Status labels  
in progress | blocked | needs review

# Component labels
frontend | backend | database | ui/ux

Setting Up Milestones​

Milestones group issues into targeted goals with deadlines:

Creating a Milestone
Title: User Authentication v1.0
Description: Complete user login, registration, and password reset functionality
Due Date: December 15, 2024

Assigning Issues and Mentions​

Assign issues to team members and use @mentions to notify specific people:

Issue with Assignments and Mentions
@developer-team This issue requires backend changes for the login API.

Assigned to: @janesmith
Labels: backend, high priority, bug

Introduction to GitHub Projects​

GitHub Projects provide kanban-style boards to visualize and manage work. You can create project boards at the repository, organization, or user level.

Creating a Project Board​

  1. Go to your repository → Projects → New project
  2. Choose a template (Basic kanban, Automated kanban, or Bug triage)
  3. Customize columns to match your workflow

A typical project board might have these columns:

To Do → In Progress → Code Review → Testing → Done

Adding Issues to Projects​

You can add issues to projects in several ways:

  • From the issue page: Click "Projects" in the sidebar
  • From the project board: Click "+ Add cards" and search for issues
  • Using issue templates: Include project assignment in your templates

Advanced Issue Features​

Issue Templates​

Create standardized issue templates by adding .github/ISSUE_TEMPLATE/ to your repository:

.github/ISSUE_TEMPLATE/bug_report.md
name: Bug Report
description: File a bug report
title: "[Bug]: "
labels: ["bug"]
body:
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: A clear and concise description of what the bug is.

Linked Pull Requests​

When you create a pull request that references an issue, GitHub automatically links them:

Linking PR to Issue
# In your pull request description
Fixes #123
Closes #456

This automatically closes the referenced issues when the PR is merged.

Integrating Issues with Development Workflow​

Branch Naming Conventions​

Connect your branches to specific issues:

Branch Names Linked to Issues
# For feature work
git checkout -b feature/42-user-login

# For bug fixes  
git checkout -b fix/123-login-button-bug

Commit Messages Referencing Issues​

Reference issues in your commit messages:

Commit Messages with Issue References
git commit -m "Add user authentication logic

- Implement login form validation
- Add error handling for failed attempts
- Fixes #42
- Related to #45"

Common Pitfalls​

  • Vague issue titles: Use specific, descriptive titles like "Login button unresponsive after 3 failed attempts" instead of "Login broken"
  • Missing reproduction steps: Always include clear steps to reproduce bugs
  • Over-assigning labels: Use 2-4 relevant labels per issue, not every possible label
  • Ignoring project board updates: Regularly update issue status in your project board to reflect reality
  • Creating duplicate issues: Search existing issues before creating new ones

Summary​

GitHub Issues and Projects transform your repository from just a code storage space into a comprehensive project management platform. Issues track specific tasks, while Projects provide the big-picture overview of your team's progress. By combining these tools with the Git workflows you've already learned, you can maintain clear communication, organized work tracking, and smooth collaboration throughout your development process.

Quiz​

GitHub Issues and Project Management – Quick Check

What is the primary purpose of GitHub Issues?

Question 1/4