Where does this file go in my repo?

Place it at .github/ISSUE_TEMPLATE/bug_report.yml. GitHub automatically detects files in that folder and offers them as choices when a user clicks New Issue.

What is the difference between an issue form and a markdown template?

A YAML issue form renders structured input fields with validation, while an older markdown template is just pre-filled text. Forms produce cleaner, more consistent reports because reporters fill labelled boxes instead of editing prose.

How do required fields work?

Each field can set validations.required to true. GitHub blocks submission until those fields are filled, which guarantees you always get reproduction steps and a description before a bug lands in your queue.

Can I auto-apply labels and assignees?

Yes. The labels key attaches one or more labels to every issue created from the form, and the assignees key auto-assigns people. This tool adds both to the top-level form metadata.

What field types are used?

The form uses textarea blocks for free-form sections like steps and behavior, an input for the version, and a dropdown is available for environment. Markdown blocks add instructions that are not submitted with the issue.

GitHub Bug Report Issue Template Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

GitHub issue forms turn vague bug reports into structured, validated submissions. This builder generates a complete bug_report.yml with the sections maintainers actually need — reproduction steps, expected versus actual behavior, environment, and screenshots — using the modern YAML issue-form schema.

How it works

The file is a YAML document with top-level metadata (name, description, title, labels, assignees) and a body array of typed fields. Each field has a type (textarea, input, dropdown, or markdown), an id, and attributes like the label and placeholder. Required fields set validations.required: true:

- type: textarea
  id: steps
  attributes:
    label: Steps to Reproduce
    placeholder: |
      1. Go to '...'
      2. Click on '...'
      3. See error
  validations:
    required: true

GitHub reads any file under .github/ISSUE_TEMPLATE/ and presents it as a guided form when someone opens a new issue, applying your default labels and assignees automatically.

Tips and notes

Keep at least the reproduction steps and a description required — those two fields prevent the most common “cannot reproduce” back-and-forth. The title prefix (for example [Bug]: ) makes bugs easy to filter in your issue list. If you also add a config.yml in the same folder you can disable blank issues so every report flows through a form.