GitHub Issues with a "bug" label are the simplest way to track bugs in your project. Create a bug report template so every report includes steps to reproduce, expected behavior, and screenshots. Use priority labels like "critical" and "low-priority" to help your team fix the most important bugs first. No coding required.
Why GitHub Issues Are Perfect for Bug Tracking
Every software project has bugs — things that do not work as expected. The key is having a reliable system to report, prioritize, and track them. GitHub Issues gives you exactly that, built right into your repository. When someone finds a bug, they create an issue with the "bug" label. A good bug report includes what happened, what should have happened, and steps to reproduce the problem. Bug report templates standardize this so every report has the same structure. Priority labels (critical, high, medium, low) tell your developer or AI tool like Cursor which bugs to fix first. You can filter the Issues list to show only bugs, only critical bugs, or bugs assigned to a specific person. As bugs get fixed through Pull Requests, they close automatically if linked with "Closes #X." This creates a complete history from discovery to resolution.
Prerequisites
- A free GitHub account
- A repository where you have write access
- A modern web browser
Step-by-step guide
Create bug-tracking labels in your repository
Create bug-tracking labels in your repository
Navigate to your repository on github.com. Click the "Issues" tab, then click "Labels" to the right of the search bar. GitHub comes with a default "bug" label (red), but you need priority labels too. Click the green "New label" button. Create these labels one by one: "critical" (dark red, #B60205), "high-priority" (orange, #D93F0B), "medium-priority" (yellow, #FBCA04), and "low-priority" (green, #0E8A16). For each, type the name, pick a color by entering the hex code, add an optional description, and click "Create label."
Expected result: Your Labels page shows the default "bug" label plus four priority labels with distinct colors.
Create a bug report issue template
Create a bug report issue template
Go to your repository's main Code tab. Click "Add file" in the top-right area and select "Create new file." In the file name field, type ".github/ISSUE_TEMPLATE/bug-report.md" — GitHub will automatically create the folders. Paste the bug report template from the complete code section below into the file editor. Scroll down, type a commit message like "Add bug report template," and click the green "Commit changes" button. Now, whenever someone clicks New issue, they will see this template as an option.
Expected result: The file .github/ISSUE_TEMPLATE/bug-report.md appears in your repository, and new issues offer this template.
Report a bug using the template
Report a bug using the template
Click the "Issues" tab and then the green "New issue" button. You should see your bug report template listed — click "Get started" next to it. The form opens pre-filled with section headings. Fill in each section: describe the bug in plain language, list the exact steps to reproduce it (step 1, step 2, step 3), explain what you expected to happen, and describe what actually happened. Drag and drop a screenshot into the text box if you have one. On the right sidebar, click "Labels" and add "bug" plus the appropriate priority label (like "critical" or "low-priority"). Assign it to someone and click "Submit new issue."
Expected result: A new issue appears with the bug label, a priority label, and a well-structured description following the template.
Filter issues to see only bugs or specific priorities
Filter issues to see only bugs or specific priorities
On the Issues page, you will see a search and filter bar at the top. Click "Label" in the filter dropdown and select "bug" to show only bug reports. To narrow further, add a priority filter — click the search bar and type "label:critical" to see only critical bugs. You can combine filters: "is:open label:bug label:high-priority" shows only open, high-priority bugs. Save these filtered views by bookmarking the page URL — the filters are preserved in the URL.
Expected result: The Issues list shows only bugs matching your selected labels, with all other issues hidden.
Track bug resolution through linked Pull Requests
Track bug resolution through linked Pull Requests
When a developer or AI tool fixes a bug, they create a Pull Request with "Closes #X" in the description (where X is the bug issue number). You can track this from the issue page — look for a "linked pull request" reference in the sidebar or timeline. Once the PR is merged, the issue closes automatically and shows a purple "Closed" badge. To review all fixed bugs, go to the Issues tab and click "Closed" to see the resolved bug list with links to the PRs that fixed them.
Expected result: Closed bug issues show links to the Pull Requests that resolved them, creating a complete fix history.
Complete working example
1---2name: Bug Report3about: Report something that is not working correctly4title: "[Bug] "5labels: bug6assignees: ''7---89## Describe the Bug10A clear description of what is broken.1112## Steps to Reproduce131. Go to '...'142. Click on '...'153. Scroll down to '...'164. See the error1718## Expected Behavior19What should have happened.2021## Actual Behavior22What actually happened instead.2324## Screenshots25Drag and drop screenshots here if available.2627## Device and Browser28- Device: [Desktop / Mobile]29- Browser: [Chrome / Safari / Edge / Firefox]30- Screen size: [if relevant]3132## Priority33- [ ] Critical — app is unusable34- [ ] High — major feature broken35- [ ] Medium — noticeable but has a workaround36- [ ] Low — minor visual or cosmetic issue3738## Additional Context39Anything else that might help fix this.Common mistakes when tracking Bugs Using GitHub Issues and Labels
Why it's a problem: Reporting a bug with just "it's broken" and no details
How to avoid: Use the bug report template to include steps to reproduce, expected behavior, actual behavior, and a screenshot. The more detail, the faster the fix.
Why it's a problem: Not assigning a priority to bug reports
How to avoid: Always add a priority label (critical, high, medium, low). Without priority, developers do not know which bugs to fix first.
Why it's a problem: Creating duplicate bug reports for the same issue
How to avoid: Search existing issues before creating a new one. Use the search bar on the Issues page and type keywords from the bug to check if it has been reported.
Why it's a problem: Leaving bugs open forever without reviewing them
How to avoid: Do a weekly review of open bugs. Close any that are fixed, reprioritize others, and reassign stale issues.
Why it's a problem: Not including screenshots or screen recordings with visual bugs
How to avoid: Always drag and drop a screenshot into the issue description. For complex bugs, use a free screen recording tool and paste the link.
Best practices
- Use a bug report template so every report follows a consistent structure
- Add both a "bug" label and a priority label to every bug issue
- Include steps to reproduce so the developer can see the exact problem
- Attach screenshots by dragging images directly into the description box
- Search existing issues before creating a new bug report to avoid duplicates
- Do a weekly bug review to reprioritize open bugs and verify closed ones
- Link bug-fixing Pull Requests to issues with "Closes #X" for automatic closure
- Use filters like "label:bug label:critical" to focus on the most urgent problems
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I'm a non-technical founder tracking bugs in my GitHub repository. Help me create a priority system with labels and explain how to triage bugs effectively.
Frequently asked questions
What is the difference between a bug and a feature request?
A bug is something that is broken — it does not work as intended. A feature request is something new that does not exist yet. Use the "bug" label for broken things and "enhancement" for new features.
How do I know if a bug has been fixed?
Check if the issue is closed. Click on the closed issue and look for a linked Pull Request that says "closed this via PR #X." You can also test the fix yourself in the live app.
Can AI tools like Lovable fix bugs automatically?
Yes. You can describe the bug in Lovable's chat prompt and it will attempt to fix it. The changes sync to GitHub. However, always verify the fix works before closing the issue.
How many priority levels should I use?
Four levels work well for most projects: critical (app is unusable), high (major feature broken), medium (noticeable but has a workaround), and low (minor cosmetic issue).
Can users outside my team report bugs?
On public repositories, anyone with a GitHub account can create issues. On private repositories, only invited collaborators can create issues.
Can RapidDev help set up a bug tracking workflow for my project?
Yes. RapidDev helps non-technical teams create bug report templates, configure priority labels, set up GitHub Projects boards for bug triage, and connect AI tools for faster fixes.
Should I use GitHub Issues or a separate tool like Jira for bug tracking?
For most small to mid-size projects, GitHub Issues is sufficient and keeps everything in one place. If you have a large team with complex workflows, Jira may offer more advanced features, but GitHub Issues plus GitHub Projects covers most needs.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation