Templates / GitHub issue forms

GitHub issue templates for bug reports

GitHub issue forms turn a blank issue into a form with required fields, dropdowns and checkboxes. They live in .github/ISSUE_TEMPLATE/ as YAML files, and GitHub offers them to anyone opening an issue on the repo.

Bug report

.github/ISSUE_TEMPLATE/bug_report.yml

name: Bug report
description: Something in the app is broken or doesn't work as expected.
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: Thanks for taking the time. The more of this you fill in, the sooner we can fix it.
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: And what did you expect to happen instead?
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      placeholder: |
        1. Go to ...
        2. Click ...
        3. See ...
    validations:
      required: true
  - type: input
    id: url
    attributes:
      label: Page or URL
      placeholder: https://app.example.com/checkout
  - type: dropdown
    id: browser
    attributes:
      label: Browser
      multiple: true
      options:
        - Chrome
        - Safari
        - Firefox
        - Edge
        - Other
  - type: input
    id: environment
    attributes:
      label: OS, device and screen size
      placeholder: macOS 15, MacBook Air, 1440 × 900
  - type: textarea
    id: console
    attributes:
      label: Console errors
      description: Anything red in the browser's developer console. Formatted as code automatically.
      render: shell
  - type: textarea
    id: screenshots
    attributes:
      label: Screenshots or recording
      description: Drag images or a video in here.
  - type: dropdown
    id: frequency
    attributes:
      label: How often does it happen?
      options:
        - Every time
        - Sometimes
        - Only once
    validations:
      required: true

render: shell formats whatever is pasted into the console field as a code block, so stack traces stay readable. validations: required: true won't let the issue be created without that field.

Feature request

.github/ISSUE_TEMPLATE/feature_request.yml

name: Feature request
description: Suggest something the app should do.
title: "[Feature]: "
labels: ["feature-request"]
body:
  - type: textarea
    id: goal
    attributes:
      label: What are you trying to do?
      description: The job you're trying to get done, not the solution. "Send the invoice from my phone", not "add a button".
    validations:
      required: true
  - type: textarea
    id: today
    attributes:
      label: How do you do it today?
      description: The workaround, if there is one.
  - type: dropdown
    id: importance
    attributes:
      label: How much does it matter?
      options:
        - Nice to have
        - Important
        - Blocking me
    validations:
      required: true
  - type: textarea
    id: context
    attributes:
      label: Anything else
      description: Screenshots, examples from other apps, who else needs it.

Asking for the goal rather than the solution is the most useful thing a feature request form can do: the button someone asks for is often not the best answer to what they need.

The chooser

config.yml in the same folder controls the page GitHub shows before the form. This one turns off blank issues and points questions somewhere else:

.github/ISSUE_TEMPLATE/config.yml

blank_issues_enabled: false
contact_links:
  - name: Ask a question
    url: https://github.com/acme/web/discussions
    about: For questions rather than bugs.

Issues from people who'll never open GitHub

Issue forms work for people who use GitHub. Your app's users don't, so their bugs reach you as emails and support tickets. Brainbox's GitHub integration files their reports straight into the repo instead, with the screenshot they marked up, their words, the browser and the console errors already in the issue, labelled the way you choose.

Try it before you install it

The button in the corner of this page is the real widget. Report something on this page and it lands in our inbox, the way your users’ reports will land in yours.

Get started