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.
- 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.
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.
| 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
The highlighted stages represent a typical team workflow. Actual issue handling may include additional review, testing, or reopening steps.
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
- Sign in to GitHub.
- Open the repository where the issue belongs.
- Select the Issues tab.
- Select New issue.
- Enter a meaningful title and description.
- Add labels, assignees, or a milestone when appropriate.
- 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
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.
| 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.
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.
#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."
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.
| 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
| 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.
13. Common Mistakes When Working with GitHub Issues
| 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
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.gh issue create, gh issue list, gh issue view, and gh issue close.15. Hands-On Practice
Now apply what you have learned by creating and managing issues in a practice repository.
Objective: Report a defect in a sample employee-management application.
- Create a repository named
employee-management, or use an existing practice repository. - Create an issue titled
[Bug] Employee search returns inactive employees. - Add reproduction steps and expected versus actual behaviour.
- Add a
buglabel. - Assign the issue to yourself.
Expected result: The repository contains a clearly documented, assigned bug issue.
Objective: Practise issue-to-code traceability.
- Create a branch named
fix/employee-search-inactive. - Implement a suitable fix in your practice application.
- Commit and push the changes.
- Open a pull request.
- Add
Closes #ISSUE_NUMBERto its description.
Expected result: The pull request references the issue and, when merged into the default branch, can automatically close it.
Objective: Standardise bug reports for your repository.
- Create
.github/ISSUE_TEMPLATE/bug_report.yml. - Add fields for the problem, reproduction steps, expected behaviour, and actual behaviour.
- Commit the template.
- 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.