LATEST 🚀 Welcome to Upgradix by Shrash Studio – Your destination for free technology learning and career growth.
🕘 Updated:
Git & GitHub

GitHub Issues – Bug Tracking and Task Management

When multiple developers work on a project, bugs, feature requests, and small tasks need to be tracked properly. GitHub Issues helps teams record these items, assign owners, discuss solutions, and follow progress.

GitHub Issues – Bug Tracking and Task Management

Imagine your team is building an online banking application. A customer reports that the transaction history page displays duplicate transactions. At the same time, another developer is working on a new account statement feature, and the QA team has identified a problem with password reset.

How will the team record these problems, decide their priority, assign owners, discuss possible solutions, and track progress without losing information in emails or chat messages?

GitHub Issues provides a shared place to report bugs, request features, discuss improvements, and manage development tasks directly alongside the source code.

In this article, you will learn:
  • What GitHub Issues are and why development teams use them.
  • How to create, assign, label, prioritise, and close issues.
  • How issues connect with branches, commits, and pull requests.
  • How to use issue templates, milestones, and GitHub Projects.
  • How to manage issues using the GitHub CLI.
  • Best practices for reliable bug tracking and task management.

1. What Are GitHub Issues?

GitHub Issues is a built-in collaboration feature that helps a repository's team track work. An issue represents a unit of work or a discussion that needs attention.

An issue can describe a software defect, a feature request, a technical improvement, documentation work, a question, or another task related to the project.

For example, a banking application repository may contain issues such as:

  • Bug: Transaction history shows duplicate records after refreshing the page.
  • Feature: Add an option to download monthly account statements.
  • Enhancement: Improve the response time of the customer search API.
  • Documentation: Add API authentication examples to the developer guide.
Important: GitHub Issues are not limited to bugs. They can represent almost any piece of work that needs discussion, ownership, prioritisation, or tracking.

2. Why Do Development Teams Use Issues?

Without a central tracking system, teams often depend on chat messages, emails, spreadsheets, or verbal instructions. Important work can get missed, duplicated, or forgotten.

GitHub Issues keeps the discussion connected to the repository and provides a visible history of the work.

Problems solved by GitHub Issues
Team challenge How GitHub Issues helps
Bug reports are scattered across chats. Record defects in one searchable location.
No clear task ownership. Assign issues to responsible team members.
Urgent tasks are difficult to identify. Use labels and prioritisation conventions.
Requirements are unclear. Discuss details and add comments to the issue.
Work progress is difficult to follow. Track open and closed issues and use Projects for broader workflows.
Completed code is not connected to the request. Reference issues from branches, commits, and pull requests.

3. Understanding the Structure of a GitHub Issue

An issue contains more than a title and description. It can include metadata and collaboration features that help the team understand and manage the work.

3.1 Issue title

The title should clearly describe the problem or task. Avoid vague titles such as Fix issue or Something is broken.

Prefer a title such as:

[Bug] Transaction history displays duplicate entries after refresh

3.2 Issue description

The description provides the context required to understand and work on the issue. For a bug report, include the steps to reproduce the problem, expected behaviour, actual behaviour, and relevant environment details.

3.3 Assignees

Assignees identify the GitHub users responsible for working on an issue. Assigning an issue makes ownership visible, but it does not automatically change the issue's status or guarantee that work has started.

3.4 Labels

Labels categorise issues so that team members can filter and understand them quickly.

bug feature documentation priority:high good first issue

3.5 Milestones

A milestone groups issues associated with a target or release. For example, a team may use a milestone named Release 2.4 to track the work planned for that release.

3.6 Comments and references

Team members can add comments to clarify requirements, share investigation results, discuss implementation choices, and link related pull requests or other issues.

4. How an Issue Moves from a Report to a Completed Fix

Consider the duplicate transaction problem in our banking application. A customer reports the issue, the development team investigates it, a developer implements a fix, and the team reviews the change before it is merged.

GitHub Issue lifecycle – from report to resolution

A reported bug moves through triage, assignment, development, pull request review, and closure. Report Bug found and recorded Triage Review details Assign Choose owner Develop Implement the fix Review Pull request checks Close Fix merged The issue remains available as the discussion and work history Traceability Issue ↔ branch ↔ commit ↔ pull request

The highlighted stages represent a typical team workflow. Actual issue handling may include additional review, testing, or reopening steps.

Step 1 – Report the problem A tester creates an issue with a meaningful title, reproduction steps, expected result, and actual result.
Step 2 – Triage the issue The team checks whether the report is valid, requests missing information, adds labels, and determines priority.
Step 3 – Assign an owner The issue is assigned to a developer or another responsible team member.
Step 4 – Implement the solution The developer creates a branch, makes the change, and commits the implementation.
Step 5 – Review and test A pull request is opened. Reviewers inspect the code and automated checks run before the change is merged.
Step 6 – Close the issue The issue is closed when the work is completed according to the team's process. A pull request can automatically close it when merged if a supported closing keyword is used.

5. Creating Your First GitHub Issue

Let's create an issue for the duplicate transaction problem in an existing repository.

5.1 Open the repository

  1. Sign in to GitHub.
  2. Open the repository where the issue belongs.
  3. Select the Issues tab.
  4. Select New issue.
  5. Enter a meaningful title and description.
  6. Add labels, assignees, or a milestone when appropriate.
  7. Select Submit new issue.

Example issue title:

[Bug] Transaction history displays duplicate entries after refresh

Example issue description:

## Problem
The transaction history page sometimes displays duplicate
transactions after the user refreshes the page.

## Steps to Reproduce
1. Sign in to the banking application.
2. Open the transaction history page.
3. Refresh the browser.
4. Observe the transaction list.

## Expected Behaviour
Each transaction should appear only once.

## Actual Behaviour
Some transactions appear more than once after refresh.

## Impact
Users may misunderstand their account activity.

## Environment
- Application: Banking Web
- Area: Transaction History
- Environment: Test
Tip: A good bug report helps another developer reproduce the issue without repeatedly asking the reporter for basic details.

6. Managing Issues with Labels, Assignees, and Milestones

6.1 Use labels to categorise work

Labels make it easier to identify the type, priority, and context of an issue. A team can create its own labels based on its workflow.

Example label strategy for a development team
Label Purpose Example
bug Defect in existing behaviour Duplicate transactions
feature New capability Download account statement
enhancement Improve existing functionality Improve search performance
documentation Documentation changes Update API guide
priority:high Urgent team priority Payment failure
good first issue Suitable for a new contributor Fix a small documentation error

6.2 Assign issues to team members

Assign an issue to the person who will take responsibility for the next action. For example, a transaction-history defect may be assigned to the developer responsible for the transaction API.

Keep assignments realistic. Assigning too many issues to one person can hide capacity problems rather than solve them.

6.3 Group work using milestones

Milestones help teams group issues around a release, sprint, or delivery target. For example:

  • Release 2.4: Issues required before the next application release.
  • API Modernisation: Issues related to upgrading service endpoints.
  • Security Improvements: Issues related to authentication and authorisation.
Remember: Labels, assignees, and milestones are different. A label categorises work, an assignee indicates ownership, and a milestone groups work toward a target.

7. Connecting Issues with Branches, Commits, and Pull Requests

One of the most useful GitHub capabilities is connecting an issue to the code changes that address it. This gives reviewers and maintainers a clear path from the original problem to the implementation.

7.1 Create a branch for the issue

Assume the issue number is #42. Create a branch with a descriptive name that includes the issue number.

git switch main
git pull origin main
git switch -c fix/42-duplicate-transactions

The branch name is a team convention. Including the issue number makes it easier to identify the work.

7.2 Commit the fix

git add .
git commit -m "Fix duplicate transaction history entries"
git push -u origin fix/42-duplicate-transactions

7.3 Reference the issue in a pull request

When opening the pull request, include a description that explains the change and references the issue.

## Summary
Fix duplicate transaction entries after refreshing
the transaction history page.

## Changes
- Corrected transaction list handling.
- Added regression test coverage.

## Related Issue
Closes #42

GitHub recognises supported closing keywords when they are used in the description of a pull request targeting the repository's default branch. When that pull request is merged, the referenced issue can be closed automatically.

7.4 Supported closing keywords

Closes #42
Fixes #42
Resolves #42

Close #42
Fix #42
Resolve #42

These keywords can also be used with supported cross-repository references when the required repository and issue reference are provided.

Important distinction: Mentioning an issue with #42 creates a reference. Using a closing keyword such as Closes #42 in the appropriate pull request description tells GitHub to close the issue when the pull request is merged.

8. Using Issue Templates

When many people report bugs, the quality of issue descriptions can vary. Some reports may not include reproduction steps, environment information, or expected behaviour.

Issue templates provide a consistent structure so contributors know what information to include.

8.1 Create a bug report template

Inside the repository, create the following file:

.github/ISSUE_TEMPLATE/bug_report.yml

Example YAML configuration:

name: Bug Report
description: Report a reproducible problem
title: "[Bug]: "
labels:
  - bug
body:
  - type: markdown
    attributes:
      value: |
        Thank you for helping improve the application.

  - type: textarea
    id: problem
    attributes:
      label: Describe the problem
      description: Explain what is happening.
      placeholder: Describe the issue clearly.
    validations:
      required: true

  - type: textarea
    id: reproduction
    attributes:
      label: Steps to reproduce
      description: Provide the exact steps.
      placeholder: |
        1. Open the application.
        2. Navigate to the affected page.
        3. Perform the action.
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: Expected behaviour
    validations:
      required: true

  - type: textarea
    id: actual
    attributes:
      label: Actual behaviour
    validations:
      required: true

  - type: input
    id: environment
    attributes:
      label: Environment
      placeholder: Browser, OS, application version

Once the template is committed to the repository, contributors can select it when creating an issue. GitHub uses the template to guide the contributor through the required fields.

8.2 Common template types

  • Bug report: Reproduction steps, expected behaviour, actual behaviour, and environment.
  • Feature request: Business need, proposed behaviour, and acceptance criteria.
  • Documentation request: Missing or incorrect documentation and suggested improvement.

9. Using GitHub Issues from the Command Line

Developers can manage issues from the terminal using the GitHub CLI, commonly called gh. This is useful when working directly from a local repository.

Install and authenticate the GitHub CLI before running these commands. Official installation instructions are available at cli.github.com.

9.1 Check authentication

gh auth status

9.2 Create an issue

gh issue create \
  --title "[Bug] Duplicate transaction history entries" \
  --body "Transactions appear more than once after refresh." \
  --label "bug" \
  --assignee "@me"

This creates an issue in the repository associated with the current directory, provided the repository and authentication are configured correctly.

9.3 List open issues

gh issue list

Example output

Showing 3 of 3 open issues in owner/banking-application

42  OPEN  [Bug] Duplicate transaction history entries
39  OPEN  [Feature] Download account statement
35  OPEN  [Enhancement] Improve customer search response time

The exact output depends on the repository and the issues available to your account.

9.4 View a specific issue

gh issue view 42

9.5 Edit an issue

gh issue edit 42 --add-label "priority:high"
gh issue edit 42 --add-assignee "@me"

9.6 Close an issue

gh issue close 42 --comment "Fix merged and verified."
CLI tip: Run gh issue --help or gh issue create --help to view the available options for your installed GitHub CLI version.

10. GitHub Issues vs GitHub Projects

GitHub Issues and GitHub Projects work together, but they solve different problems.

An issue records a specific piece of work or discussion. A project provides a broader way to organise and visualise work across multiple issues and other project items.

GitHub Issues and GitHub Projects comparison
Area GitHub Issues GitHub Projects
Primary purpose Track individual work items and discussions. Organise and manage work across a broader workflow.
Typical content Bugs, feature requests, tasks, questions. Issues, pull requests, and project items.
Organisation Labels, assignees, milestones. Views, fields, filters, and grouping.
Discussion Comments and issue activity. Work planning and project-level visibility.
Example Fix duplicate transaction records. Track all work planned for Release 2.4.

A team may create an issue for every bug or feature and then add relevant issues to a GitHub Project to manage the overall delivery workflow.

11. Searching and Filtering Issues

As a repository grows, it may contain hundreds or thousands of issues. GitHub provides search qualifiers that help find relevant work quickly.

Examples of issue search queries:

is:issue is:open
is:issue is:closed
is:open label:bug
is:open assignee:@me
is:open label:priority:high
is:issue milestone:"Release 2.4"
is:issue author:username
is:issue no:assignee
Useful issue search qualifiers
Qualifier Meaning
is:open Find open items.
is:closed Find closed items.
label:bug Find items with the bug label.
assignee:@me Find items assigned to the signed-in user.
no:assignee Find items without an assignee.
author:username Find items created by a specific user.

Search qualifiers can be combined to narrow the results. For example, is:open label:bug assignee:@me finds open bug issues assigned to the current user.

12. Issue Management Best Practices

12.1 Write clear and actionable titles

Use a title that describes the actual problem or requested outcome. A clear title makes search results and project boards easier to understand.

12.2 Include enough information to reproduce bugs

Provide steps, expected results, actual results, environment details, and relevant logs or screenshots where appropriate. Remove secrets and personal data before sharing diagnostic information.

12.3 Use labels consistently

Agree on a small, meaningful set of labels. Avoid creating several labels with nearly identical meanings.

12.4 Keep issues focused

One issue should normally describe one coherent problem or deliverable. If a task contains several independent pieces of work, consider splitting it into separate issues and linking them.

12.5 Avoid using issues as a substitute for incident response

Production incidents may require a dedicated incident-management process, immediate communication, escalation, and operational coordination. An issue can record follow-up work, but it should not be the only mechanism for handling a live incident.

12.6 Close issues only when the work is complete

Use the team's agreed completion criteria. If the problem is not actually resolved, keep the issue open or reopen it with updated information.

12.7 Review stale issues

Periodically review old issues, remove duplicates, request missing information, and close work that is no longer relevant according to the team's policy.

Security reminder: Never paste access tokens, passwords, private customer information, payment details, or production secrets into public issues. Use approved private channels for sensitive incident details.

13. Common Mistakes When Working with GitHub Issues

Common mistakes and better approaches
Mistake Better approach
Creating an issue with a vague title. Describe the affected feature and observed problem.
Reporting a bug without reproduction steps. Include clear, numbered reproduction steps.
Assigning every issue to one developer. Distribute ownership based on expertise and capacity.
Using labels inconsistently. Define a shared label convention.
Closing an issue before verifying the fix. Follow the team's testing and completion criteria.
Creating duplicate issues. Search existing issues before creating a new one.
Sharing confidential information. Use approved secure reporting channels.

14. Interview Questions and Answers

Q1. What are GitHub Issues? GitHub Issues is a repository collaboration feature used to record, discuss, and track bugs, feature requests, improvements, and other work items.
Q2. Are GitHub Issues used only for bug tracking? No. They are also used for feature requests, enhancements, documentation tasks, questions, and general project work.
Q3. What is the difference between an issue and a pull request? An issue describes work or a problem that needs attention. A pull request proposes code changes and provides a place for review and discussion before those changes are merged.
Q4. What is the purpose of labels? Labels categorise issues and help teams filter and prioritise work. Examples include bug, feature, documentation, and priority:high.
Q5. What is an assignee? An assignee is a GitHub user responsible for taking action on an issue. It makes ownership visible to the team.
Q6. What is a milestone? A milestone groups issues and pull requests around a target, such as a release or delivery objective.
Q7. How can a pull request automatically close an issue? Add a supported closing keyword, such as Closes #42, to the pull request description. When the pull request is merged into the repository's default branch, GitHub can automatically close the referenced issue.
Q8. What is the purpose of an issue template? An issue template guides contributors to provide consistent information when reporting bugs or requesting features. It improves the quality of issue descriptions.
Q9. What is the difference between GitHub Issues and GitHub Projects? Issues track individual work items and discussions. Projects organise work across multiple items and provide views and fields to manage the broader workflow.
Q10. Can GitHub Issues be managed from a terminal? Yes. The GitHub CLI provides commands such as gh issue create, gh issue list, gh issue view, and gh issue close.
Q11. Can an issue be assigned to multiple developers? GitHub supports assigning issues to multiple users, subject to repository and product limits. Teams should still make the primary ownership and next action clear.
Q12. What should a good bug report contain? A useful bug report normally includes a clear title, problem description, reproduction steps, expected behaviour, actual behaviour, environment details, and relevant non-sensitive diagnostic information.

15. Hands-On Practice

Now apply what you have learned by creating and managing issues in a practice repository.

Exercise 1 – Create a bug issue

Objective: Report a defect in a sample employee-management application.

  1. Create a repository named employee-management, or use an existing practice repository.
  2. Create an issue titled [Bug] Employee search returns inactive employees.
  3. Add reproduction steps and expected versus actual behaviour.
  4. Add a bug label.
  5. Assign the issue to yourself.

Expected result: The repository contains a clearly documented, assigned bug issue.

Exercise 2 – Connect an issue to a pull request

Objective: Practise issue-to-code traceability.

  1. Create a branch named fix/employee-search-inactive.
  2. Implement a suitable fix in your practice application.
  3. Commit and push the changes.
  4. Open a pull request.
  5. Add Closes #ISSUE_NUMBER to its description.

Expected result: The pull request references the issue and, when merged into the default branch, can automatically close it.

Exercise 3 – Create an issue template

Objective: Standardise bug reports for your repository.

  1. Create .github/ISSUE_TEMPLATE/bug_report.yml.
  2. Add fields for the problem, reproduction steps, expected behaviour, and actual behaviour.
  3. Commit the template.
  4. Open the new issue page and verify that the template is available.

Expected result: Contributors can create bug reports using the standard template.

16. Conclusion

GitHub Issues gives development teams a practical way to record problems, discuss requirements, assign ownership, and track work alongside the source code. With clear descriptions, useful labels, milestones, and issue templates, teams can make their development process more organised and transparent.

Connecting issues with branches, commits, and pull requests also improves traceability. A team can understand why a change was made, which work item it addresses, and how the solution was reviewed.

For individual developers, learning GitHub Issues is an important part of understanding real-world software development. For teams, using it consistently helps turn scattered requests into visible, manageable work.

Key takeaway: A well-written GitHub Issue explains what needs attention, why it matters, and how the team can move the work toward completion.

17. Official Documentation and Further Learning

Comments & Ratings (0)

Log in or create a student account to comment and rate this article.

Be the first to comment on this article.