Skip to content
Swingback, home

BlogDevelopers

Bug report template: a GitHub issue form you can copy

A bug report template as a GitHub issue form to copy: what happened, the steps, the version and logs, with a config.yml that sends feature requests elsewhere.

By Elie Baier · · Updated · 5 min read

A good bug report template asks for four things before anything else: what happened, what the person expected instead, the steps that make it happen, and the version and the browser or OS they were on. How often it happens comes next, and logs and screenshots last. Below is one as a GitHub issue form you can copy, a config.yml that keeps feature requests and questions out of your bug tracker, and what to do when the people who find bugs are customers without a GitHub account.

What a bug report needs#

Most bug reports that can't be fixed miss the same things. A report is worth working on when it says:

  • What happened, in the reporter's words: the error message, the wrong number, the button that did nothing.
  • What they expected. Many "bugs" are a difference of opinion, and this line tells you which ones.
  • Steps that reproduce it, from a fresh start. "Sometimes it breaks" becomes "open a project, rename it, press Back".
  • The version and the environment: the app's version, the browser or OS, and anything unusual about their setup.
  • How often: every time, sometimes, or once. A bug that happened once and never again is triaged differently.
  • Evidence: a log, a stack trace, a screenshot or a short recording.

The form asks for them in that order. Everything but the evidence is required: not every bug leaves a log, or shows in a screenshot.

The template, as a GitHub issue form#

Issue forms are YAML files in .github/ISSUE_TEMPLATE. GitHub shows them as a form instead of a blank text box, and writes each answer into the issue under its label. Save this as .github/ISSUE_TEMPLATE/1-bug-report.yml on your default branch:

YAML
name: Bug report
description: Something doesn't work the way it should.
title: "[Bug]: "
labels: ["bug"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for reporting this. The steps to reproduce it matter most: with them, we can usually fix it.
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: The error message, the wrong result, or what did nothing.
      placeholder: I renamed a project and pressed Back. The list still showed the old name until I reloaded.
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: What did you expect instead?
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      description: From a fresh start, one step a line.
      value: |
        1.
        2.
        3.
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: Shown under Settings → About.
      placeholder: "2.4.1"
    validations:
      required: true
  - type: input
    id: environment
    attributes:
      label: Browser or OS
      description: And anything unusual about your setup, such as an extension or a VPN.
      placeholder: "Safari 19 on macOS 26"
    validations:
      required: true
  - type: dropdown
    id: frequency
    attributes:
      label: How often does it happen?
      options:
        - Every time
        - Sometimes
        - It happened once
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Logs
      description: Paste any error output. It's formatted as code, so no backticks are needed.
      render: shell
  - type: upload
    id: screenshots
    attributes:
      label: Screenshots or a recording
      description: Optional, if they show the problem better than words.
  - type: checkboxes
    id: searched
    attributes:
      label: Before you send it
      options:
        - label: I searched the open issues and found none like this one.
          required: true

What GitHub's documentation says about these fields, as of October 2026:

  • Issue forms are in public preview, so the syntax may still change.
  • required only works in public repositories. In a private one, every field can be left empty.
  • render turns a textarea into a code block, which is what you want for logs and stack traces.
  • upload is a field for files, such as screenshots, recordings or log archives.
  • A label must already exist, or it's left off the issue. bug is one of the labels a new repository starts with.
  • Your organization's issue types work too. If it defines a "Bug" type, type: bug beside labels sets it.

Fill it in from your app#

Each field's id also names it in the address of a new issue. A "Report a bug" link in your app can send people to the form with their version already filled in:

Text
https://github.com/your-org/your-app/issues/new?template=1-bug-report.yml&version=2.4.1

They can't get the version wrong if they never have to type it.

Bugs here, requests and questions elsewhere#

A bug tracker fills up with things that aren't bugs: "it would be nice if…", "how do I…". A config.yml in the same folder decides what the template chooser offers:

YAML
blank_issues_enabled: false
contact_links:
  - name: Request a feature
    url: https://feedback.example.com
    about: Ideas and requests go on our feedback board, where others can vote for them.
  - name: Ask a question
    url: https://example.com/support
    about: For help using the product.

With blank_issues_enabled: false, people without write access can only open issues through your forms. If requests stay on GitHub too, add a second form for them: the feature request template is one to copy, and the 1- prefix keeps the bug form first in the list.

When the people who find bugs aren't on GitHub#

An issue form works when your users have GitHub accounts. A customer who hits a bug inside your product won't create one to tell you. They write to support, or they leave.

A feedback board inside the app takes those reports where they happen. Give it a board called "Bugs", and put the same questions in the board's description: what happened, what you expected, the steps, and a screenshot. Customers write in their own words, and the people who hit the same bug vote for that report instead of writing it again. The votes tell you how many people it affects.

From there, with Swingback's sync Beta, a member creates the GitHub issue from the report, with a title and a text written for engineers. Swingback adds no name, email or company of the person who reported it: the issue's text is what the member confirms before it's created.

A post linked to its issues on GitHub and in Linear: when the last one closes, the post completes and the people who voted hear about it. A bug report on a board works the same way.

When the fix merges and the issue closes as completed, the report completes too, and everyone who reported, voted for or commented on it hears that it's fixed. On GitHub, the person who opened an issue sees it close. On a board, so do the twenty customers who hit the same bug and never opened anything.

GitHub and Linear in the docs has how an issue is created from a report, and what each state of the issue does to it. If you're weighing a board against issues altogether, GitHub issues for feature requests goes through when each is enough.