GitHub Issues can work well for small teams, but only if the issue has enough context for someone to reproduce the problem. A blank issue box usually pushes that cleanup work onto the developer who receives it.
Use this template when bugs arrive through Slack, email, support, Discord, client notes, or screenshots and need to become a clean GitHub issue.
Markdown template
Add this as .github/ISSUE_TEMPLATE/bug_report.md if you want a simple text template.
---
name: Bug report
about: Report a reproducible product bug
title: "[Bug]: "
labels: bug, needs-triage
---
Summary
What broke?
Who is affected?
- Customer/account:
- Plan or segment:
- Number of reports:
Steps to reproduce
Expected behavior
What should have happened?
Actual behavior
What happened instead?
Environment
- URL or product area:
- Browser and version:
- Device or OS:
- App version or deploy window:
Evidence
Screenshots, recordings, logs, support tickets, or related issues:
Impact and workaround
- Severity:
- Is there a workaround?
Is revenue, data, trust, accessibility, or a release at risk?
Issue form version
GitHub also supports issue forms with structured fields. Use this as .github/ISSUE_TEMPLATE/bug_report.yml if your team wants required fields and cleaner prompts.
name: Bug report
description: Report a reproducible product bug
title: "[Bug]: "
labels: ["bug", "needs-triage"]
body:
- type: markdown
attributes:
value: "Use this form to give engineering enough context to reproduce and prioritize the bug."
- type: textarea
id: summary
attributes:
label: Summary
description: What broke?
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
description: List the smallest set of steps that triggers the issue.
placeholder: |
1. Go to...
2. Click...
3. See...
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
description: What should have happened?
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual behavior
description: What happened instead?
validations:
required: true
- type: input
id: affected-url
attributes:
label: Affected URL or product area
- type: textarea
id: environment
attributes:
label: Environment
description: Browser, device, OS, app version, deploy window, or account state.
- type: textarea
id: evidence
attributes:
label: Evidence
description: Screenshots, recordings, logs, support tickets, or related issues.
- type: dropdown
id: impact
attributes:
label: Impact
options:
- Blocks a core workflow
- Degrades a workflow
- Cosmetic or low-risk
- Not sure yet
validations:
required: true
What this template is trying to prevent
- Issues with no reproduction steps.
- Screenshots without browser or account context.
- “It broke” reports with no expected behavior.
- Priority arguments before impact is understood.
- Duplicate issues that never link back to the first report.
How pagemarkr fits
If this template solves the problem, use it. pagemarkr is for the intake step before GitHub: collecting missing context, cleaning up the report, and preparing a copy-ready issue packet. Native GitHub routing is a roadmap item we are validating with early users.
Reference
GitHub’s docs explain where issue forms live and how the YAML body fields work: Syntax for issue forms.
Next step
Use the template above in your repo, or request early access to pagemarkr if you want a lightweight intake step before bugs reach GitHub.