Master Git & GitHub From Scratch

Clear, practical, and structured lessons designed to take you from Git fundamentals to real-world GitHub collaboration.

GitHub Issues

GitHub Issues is a built-in tool for tracking bugs, requesting features, assigning tasks, and discussing project updates directly within a GitHub repository.

Developers, project managers, and contributors can use issues to organize work, assign responsibilities, and track progress throughout the software development process.


1. Core Features of a GitHub Issue

Each issue provides several tools to help teams manage their work.

Feature Purpose Example
Title and Description Describe the problem or task. Markdown supports headings, lists, code, and checklists. Fix login validation
Assignees Identify the team members responsible for resolving an issue. Assign to a backend developer
Labels Categorize issues so they can be filtered and prioritized. bug, enhancement
Milestones Group issues around a release or project goal. v1.0.0 Release
Example: If a user reports that the login button is not working, create an issue, add the bug label, assign a developer, and track the fix until completion.

2. Creating an Issue

  1. Open your repository on GitHub.
  2. Select the Issues tab.
  3. Click New issue.
  4. Enter a clear title and detailed description.
  5. Add labels, assignees, or a milestone if needed.
  6. Click Create to submit the issue.

A good issue description explains the problem, steps to reproduce it, expected behavior, actual behavior, and any relevant error messages.


3. Connecting Issues to Branches

GitHub can connect issues to development branches and pull requests. When available, use the issue's Create a branch option to create a branch associated with the task.

For example, a branch for issue number 12 might be named:

12-fix-login-bug

Developers can make changes on this branch and then open a pull request to review and merge those changes.


4. Automatically Closing Issues

GitHub recognizes special keywords in commit messages and pull request descriptions. When the associated change is merged into the repository's default branch, these keywords can automatically close the issue.

Example commit message:

Fixes #12 - Correct the login button styling

Common closing keywords include:

  • close, closes, closed
  • fix, fixes, fixed
  • resolve, resolves, resolved
Remember: The closing keyword must reference the correct issue number. Automatic closure depends on where and how the commit or pull request is merged.

5. Using Issue Templates

Issue templates help contributors submit consistent, useful bug reports and feature requests instead of vague descriptions.

Create templates inside the following repository folder:

.github/ISSUE_TEMPLATE/

For example, a bug report template can ask for:

  • Bug summary
  • Steps to reproduce the problem
  • Expected behavior
  • Actual behavior
  • Operating system and browser details
  • Error messages or logs

GitHub supports Markdown issue templates and YAML-based issue forms, which can collect structured information from contributors.


6. GitHub Issues vs. GitHub Projects

GitHub Issues GitHub Projects
Tracks individual bugs, tasks, and feature requests. Organizes and tracks work across multiple issues and pull requests.
Provides descriptions, labels, assignees, and discussions. Provides views such as tables, boards, and roadmaps.
Best for recording and managing individual work items. Best for visualizing progress across a project.

7. Best Practices

  • Use clear and descriptive issue titles.
  • Include steps to reproduce bugs.
  • Use labels consistently across the team.
  • Assign an owner when responsibility is clear.
  • Link related branches and pull requests.
  • Close completed issues and keep project status updated.
Key Takeaway
GitHub Issues help teams track and discuss work alongside their source code. Linking issues with branches and pull requests makes development work easier to organize and review.