Free Bug Report Template for GitHub Issues

Checked by TNT Review — 5 October 2026. The template was checked for its 3 load-bearing parts: reproduction steps, an environment section, and an expected-vs-actual split — all present. See Verification.

The problem

“It doesn’t work” is the single most common and least useful bug report. Without exact reproduction steps and environment details, a maintainer often can’t even confirm the bug exists, let alone fix it — and the back-and-forth asking for that missing information is slower for everyone than including it up front.

Expected outcome

By the end of this guide you will have a bug report template that gets you a faster, more useful response, by including exactly what a maintainer actually needs on the first read.

Requirements and costs

Any text editor or GitHub’s own issue form.
Cost: free.

Step-by-step implementation

Download the template from the link below.
If you maintain a project: save it as .github/ISSUE_TEMPLATE/bug_report.md in your repo, and GitHub automatically offers it when someone clicks “New issue.”
If you’re reporting a bug: copy the template into a new issue and fill in every section — especially “Steps to reproduce,” which is the part most reports skip.
Keep the minimal example minimal. A 10-line snippet that reproduces the bug is more useful than your entire project pasted in.

A real example

“What happened: clicking Save shows a spinner forever.” vs. the useful version: “What happened: clicking Save on a form with an empty ‘name’ field shows an infinite spinner (expected: a validation error). Steps: 1. Open the form. 2. Leave Name blank. 3. Fill everything else. 4. Click Save.” The second version, with Environment filled in, is something a maintainer can act on immediately.

Verification and troubleshooting

What we actually checked: the template’s 3 load-bearing parts are present and correctly structured — “Steps to reproduce” as a numbered list, an “Environment” section, and a clear “What happened” vs. “What you expected instead” split. This is a structural check of the template file, not a record of a specific real bug report.

Troubleshooting:

You can’t reliably reproduce the bug yourself. Say so explicitly (“happens roughly 1 in 5 times, exact trigger unclear”) rather than guessing at steps that might be wrong — an honest “I can’t always reproduce this” is more useful than confidently incorrect steps.
The bug only happens in production, not locally. Note that directly in Environment — it’s a real, important clue, not something to leave out because it complicates the report.
You’re not sure if it’s really a bug or intended behavior. Report it anyway, phrased as a question (“Is this intended?”) — maintainers would rather close a non-bug than miss a real one that never got reported.

Free vs. paid

This is free and complete as a Markdown template. Paid issue-tracking tools add custom fields, automatic triage and SLA tracking — genuinely useful for larger teams, not necessary for an open-source bug report.

Free resources

The download is the full template.

Download the bug report template (ZIP, 1 KB)

Is there a paid version?

Not yet. This is the complete method. TNT Review has sold nothing to date and has no checkout, so any price we discuss in future should be read as a hypothesis, not an offer.