Skip to content
midgeDocs
Bug reportsBug report template: free, for Jira, GitHub and Linear
Bug reports

Bug report template: free, for Jira, GitHub and Linear

A free bug report template to copy and paste, ready-made versions for GitHub, Linear and Jira, a GitHub issue form, and a filled-in example.

A bug report template is a fixed set of fields that makes every report answer the same questions: what went wrong, where, how to reproduce it, what should have happened, and what evidence shows it. The template below covers title, summary, environment, steps to reproduce, expected and actual results, frequency, severity, attachments and logs. Copy it into your issue tracker, a support form or a chat message and fill in the blanks. Further down are ready-made versions for GitHub, Linear and Jira, including a GitHub issue form.

Templates exist because developers lose most of their time on missing details, not on the fix. A report with exact steps, the browser version and the console error can often be fixed the same day. A report that says “checkout is broken” turns into a long thread of questions.

The template

Title: [What is broken] when [action] on [page or feature]

Summary
One or two sentences in plain language. What happened and who is affected.

Environment
- URL:
- Browser and version:
- Operating system:
- Device / screen size:
- App version or build (if known):
- Account / role / test user:
- Date and time it happened (with time zone):

Steps to reproduce
1.
2.
3.

Expected result
What should have happened.

Actual result
What happened instead. Include the exact error message, copied as text.

Frequency
Always / Sometimes (about X out of Y tries) / Happened once

Severity
Blocker / Major / Minor / Cosmetic

Workaround
Any way to get around it, or "None found".

Attachments
- Screenshot or screen recording:
- Console errors:
- Network request that failed (URL, status, response):
- HAR file (sanitized), if requested:

Notes
Anything else: when it started, what changed recently, related tickets.

How to fill in each field

Title

The title is what people scan in a list of fifty tickets, so make it specific. A useful pattern is “what is broken” plus “when” plus “where”. “Pay button stays disabled after entering a valid card on checkout” beats “Checkout bug”. Avoid words like “urgent” or “broken” on their own; the severity field carries that.

Summary

One or two sentences a non-technical teammate can understand. Say who is affected if you know: all users, only admins, only Safari users, only one customer.

Environment

Many bugs depend on the browser, the device, the account or the data. Write down the exact URL, the browser name and version, the operating system, and the account or role you used. If the app shows a version or build number, include it. The time of the failure, with your time zone, lets the developer find the matching entries in server logs.

Steps to reproduce

This is the most important field. Number the steps, start from a known state (“signed in as a user with an empty cart”), and include the exact data you used. Write one action per step. If you could not reproduce it a second time, say so and describe what you did the first time as closely as you can.

Expected result and actual result

Keep them side by side so the gap is obvious. Copy error messages as text instead of paraphrasing them; the developer will search the code for that exact string. “Nothing happens” is a valid actual result, but add what you checked, such as “no error message, the button stays enabled”.

Frequency

“Always” bugs are the easiest to fix. “Sometimes” bugs need more data, so estimate the rate (“3 out of 10 tries”) and note anything that seems to matter, such as a slow connection or a large file.

Severity

Severity is about impact, not about how annoyed you are. A common scale:

SeverityMeaningExample
BlockerCore flow impossible, no workaroundNo one can sign in
MajorImportant feature broken or data wrong, workaround is painfulInvoices show the wrong total
MinorFeature works with a small problem or an easy workaroundSorting resets after a page reload
CosmeticVisual issue, no functional impactButton text overlaps on small screens

Priority, which decides when it gets fixed, is usually set by the team that owns the backlog, not by the reporter.

Workaround

A workaround tells the team how urgent the fix is and helps support answer customers in the meantime.

Attachments and logs

Evidence saves the most time. Attach a screenshot with the problem area marked, or a short screen recording that shows the steps. For web apps, add the console errors and the failing network request. Our guides on exporting console logs in Chrome and capturing network traffic in Chrome show how. If someone asks for a HAR file, follow how to get a HAR file and clean it with the HAR sanitizer first, because HAR files contain cookies and tokens.

A filled-in example

Title: Pay button stays disabled after entering a valid card on checkout

Summary
On the checkout page, the Pay button never becomes clickable after a valid
test card is entered, so the order cannot be placed. Seen in Chrome and Edge.

Environment
- URL: https://staging.example.com/checkout
- Browser and version: Chrome 154 on Windows 11; also Edge 154
- Device / screen size: Laptop, 1920x1080
- App version or build: web 4.18.0 (footer)
- Account / role / test user: [email protected], standard customer
- Date and time: 2026-11-10 14:32 CET

Steps to reproduce
1. Sign in as [email protected].
2. Add "Starter plan, annual" to the cart.
3. Go to /checkout.
4. Enter test card 4242 4242 4242 4242, expiry 12/30, CVC 123.
5. Click outside the card field.

Expected result
The Pay button becomes enabled and shows "Pay $120.00".

Actual result
The Pay button stays gray and disabled. No error message is shown.
The console shows: Uncaught TypeError: Cannot read properties of
undefined (reading 'postalCode') at validateCard (checkout.js:214)

Frequency
Always (5 out of 5 tries)

Severity
Blocker: customers cannot pay

Workaround
None found. Works on production build 4.17.2.

Attachments
- Screen recording: link in comments
- Console errors: checkout-console.log
- Network: POST /api/cart/validate returned 200; no other failures

Notes
Started after this morning's staging deploy.

Notice what makes this example work. The steps start from a known account. The test card is named. The console error is quoted exactly. The reporter checked another browser and the previous build, which already narrows the cause to the latest change.

Shorter versions

Not every bug needs every field. For a quick message in a team chat, a compact version is enough:

Bug: [title]
Where: [URL], [browser/OS]
Steps: 1) ... 2) ... 3) ...
Expected: ...
Actual: ...
Evidence: [screenshot / recording / console error]

For customer support teams forwarding a user’s report, add the customer’s account ID, the ticket link and the customer’s own words, and mark which parts you reproduced yourself.

For QA test runs, add the test case ID and the build under test so the bug links back to the test that found it.

Templates for GitHub, Linear and Jira

The plain text template works anywhere. If your tracker renders Markdown, this version keeps the headings and checklists readable:

markdown
## Summary
<!-- One or two sentences: what happened and who is affected. -->

## Environment
- URL:
- Browser and version:
- Operating system:
- App version or build:
- Account / role:

## Steps to reproduce
1.
2.
3.

## Expected result

## Actual result
<!-- Paste the exact error message as text. -->

## Frequency
<!-- Always / Sometimes (X out of Y) / Once -->

## Severity
<!-- Blocker / Major / Minor / Cosmetic -->

## Evidence
- [ ] Screenshot or screen recording
- [ ] Console errors
- [ ] Failed network request

GitHub Issues

Save the Markdown version as .github/ISSUE_TEMPLATE/bug_report.md in your repository, with a short header so GitHub offers it in the “New issue” picker:

markdown
---
name: Bug report
about: Something is broken
labels: bug
---

GitHub also supports issue forms, which turn the template into labeled fields that people cannot skip. Save this as .github/ISSUE_TEMPLATE/bug_report.yml:

yaml
name: Bug report
description: Something is broken
labels: ["bug"]
body:
  - type: textarea
    id: summary
    attributes:
      label: Summary
      description: What happened, and who is affected?
    validations:
      required: true
  - type: input
    id: url
    attributes:
      label: URL
  - type: input
    id: environment
    attributes:
      label: Browser, OS and app version
      placeholder: Chrome 154 on macOS 26, web 4.18.0
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      value: |
        1.
        2.
        3.
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected result
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: Actual result
      description: Paste the exact error message as text.
    validations:
      required: true
  - type: dropdown
    id: severity
    attributes:
      label: Severity
      options:
        - Blocker
        - Major
        - Minor
        - Cosmetic
  - type: textarea
    id: evidence
    attributes:
      label: Screenshots, recording and logs
      description: Drag files here or paste a link to a recording.

Linear

Linear has issue templates in a team’s settings. Create one named “Bug”, paste the Markdown version into its description, and set the Bug label and the team’s triage state, so every report starts with the same fields.

Jira

In Jira, paste the plain text or Markdown version into the description of a new Bug. Jira Cloud has no built-in default description for each issue type, so teams that want the template prefilled use an issue template app from the Atlassian Marketplace. A link to a screen recording with console and network logs goes in the description or a comment.

Mistakes the template prevents

A template is mostly a checklist against the same few mistakes:

  • Several bugs in one report. One ticket per problem, so each can be fixed, tested and closed on its own.
  • Paraphrased errors. “It said something about permissions” cannot be searched. The exact message can.
  • Missing starting point. Steps that begin halfway through a flow only work for the person who wrote them.
  • Opinions instead of observations. “The API is broken” is a guess. “POST /api/orders returned 500” is a fact the developer can check.
  • Secrets in attachments. Screenshots of admin panels, HAR files and console logs can include tokens and customer data. Crop, blur or sanitize before attaching.

Make it your team’s default

Most issue trackers let you save a default description or issue template, so every new bug starts with these headings. Keep the template short enough that people actually fill it in. If a field is empty in most reports, remove it. If developers keep asking the same follow-up question, add a field for it.

Let the tool fill the technical fields

The fields people skip most often are the technical ones: browser version, console errors, the failing request. Midge, a free Chrome extension, attaches them automatically to a screen recording or screenshot, so the reporter only writes the title, steps and expected result. Every recording includes console logs, network requests, user actions and device info. Passwords, card numbers, tokens and cookies are redacted in your browser before anything leaves your device. A report goes straight to Jira, Linear, GitHub Issues or Slack, or is shared as a link you can paste anywhere.

Frequently asked questions

What should a bug report template include?

A clear title, the environment (URL, browser, OS, app version, account), numbered steps to reproduce, expected result, actual result, how often it happens, severity, and evidence such as screenshots, a video, console logs and network requests.

Can I use this template in Jira, Linear or GitHub Issues?

Yes. It is plain text with Markdown-friendly headings, so you can paste it into any tracker. GitHub and Linear can also save it as an issue template, and Jira can with a Marketplace app.

Where do GitHub issue templates go?

In the .github/ISSUE_TEMPLATE folder of the repository. A .md file adds a Markdown template, and a .yml file adds an issue form with required fields. GitHub lists them when someone opens a new issue.

What is the difference between severity and priority?

Severity describes how badly the bug affects the product or users. Priority describes how soon the team will fix it. A severe bug in a rarely used admin screen can have lower priority than a cosmetic bug on the pricing page.

Do I need to fill in every field?

No. Title, steps, expected and actual results are essential. Fill the rest when you know it, and write unknown rather than guessing.