GitHub issue templates don’t just help you write better bug reports; they force you to capture the exact information needed to reproduce and diagnose a problem, making your entire team more efficient.
Here’s a simple bug report template in action. Imagine a user is reporting a login issue on a web app.
bug_report.md
---
name: Bug Report
about: Something isn't working as expected.
title: "[Bug] Short, descriptive title of the issue"
labels: bug
assignees: ""
---
**Describe the bug**
A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. Go to 'Login page'
2. Enter username 'testuser'
3. Enter password 'password123'
4. Click 'Login'
5. Observe the error message.
**Expected behavior**
A clear and concise description of what you expected to happen.
**Screenshots**
If applicable, add screenshots to help explain your problem.
**Desktop (please complete the following information):**
* OS: [e.g., Windows 10]
* Browser: [e.g., Chrome]
* Browser Version: [e.g., 114.0.5735.199]
**Mobile (please complete the following information):**
* Device: [e.g., iPhone 13]
* OS: [e.g., iOS 16.5]
* Browser: [e.g., Safari]
* Browser Version: [e.g., 16.5]
**Additional context**
Add any other context about the problem here.
When a developer clicks "New Issue" in a GitHub repository configured with this template, they’ll see this pre-filled form.
This structured approach ensures that when someone reports a bug, they’re providing a reproducible scenario. The template breaks down the issue into:
- A clear title: Helps with quick scanning and filtering of issues.
- A detailed description: Articulates the problem.
- Reproducible steps: This is the gold mine. It’s a step-by-step guide that, if followed precisely, should trigger the bug. This eliminates the "it works on my machine" problem.
- Expected behavior: Clarifies the intended functionality, preventing misunderstandings about what "broken" actually means.
- Screenshots: Visual evidence is incredibly powerful for debugging UI issues.
- Environment details: OS, browser, device versions are critical for identifying environment-specific bugs.
Let’s see how this plays out. A user, Sarah, encounters a login failure. Instead of a vague "Login not working," she uses the template:
Issue Title: [Bug] Login fails with "Invalid credentials" for valid users
Describe the bug: When a user with a valid username and password attempts to log in, they receive an "Invalid credentials" error message, preventing them from accessing their account.
To Reproduce:
- Navigate to
https://example.com/login - Enter username
sarah.jones - Enter password
SecureP@ss1 - Click the "Sign In" button.
- The page reloads with an error banner at the top: "Invalid credentials. Please try again."
Expected behavior:
Upon successful authentication, the user should be redirected to their dashboard page (https://example.com/dashboard).
Screenshots:
Desktop (please complete the following information):
- OS: macOS Ventura 13.4
- Browser: Firefox
- Browser Version: 115.0.2
Mobile (please complete the following information):
- Device: Google Pixel 7
- OS: Android 13
- Browser: Chrome
- Browser Version: 115.0.5790.138
Additional context: This issue started occurring this morning. It affects both desktop and mobile devices. Other users have reported similar issues.
Now, a developer, Alex, picks up this issue. He can immediately see the exact username and password Sarah used, the URL, and the error message. He can also see her environment. This allows him to:
- Reproduce locally: Alex opens Firefox on his macOS machine, goes to
https://example.com/login, and triessarah.joneswithSecureP@ss1. - Examine logs: He checks the application logs for requests originating from his IP address or matching the username
sarah.jonesaround the time he made the request. - Compare environments: If he can’t reproduce it, he compares his browser version and OS to Sarah’s.
The system works by leveraging YAML frontmatter within Markdown files stored in a .github/ISSUE_TEMPLATE directory in your repository. GitHub automatically renders these as forms when a user initiates a new issue. You can create multiple templates for different issue types (e.g., bug_report.md, feature_request.md).
What most people don’t realize is that the title and labels fields in the template’s frontmatter are directly mapped to the issue’s title and labels upon creation, saving an extra step for the reporter and ensuring consistency.
The next thing you’ll want to explore is defining custom dropdowns within your templates to standardize choices for things like severity or component, making issue triage even faster.