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.

What is the GitHub Bug Report Issue Template Builder?

Creates a structured GitHub issue form (bug_report.yml) with Steps to Reproduce, Expected and Actual Behavior, Environment, and Screenshots fields using the modern YAML issue-form schema, ready to drop into .github/ISSUE_TEMPLATE. It runs free in your browser on Gera Tools, with nothing uploaded.

GitHub Bug Report Issue Template Builder

Name: GitHub Bug Report Issue Template Builder
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

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.

Why use a YAML form instead of a Markdown template?

Older GitHub issue templates are Markdown files that pre-fill the issue body with headings and placeholder text. Reporters can delete or ignore the structure entirely, producing reports like “it doesn’t work” with no reproduction steps.

YAML issue forms are different: GitHub renders them as real HTML form fields — text areas, dropdowns, checkboxes — and can block submission until required fields are filled. The result is that maintainers consistently receive the minimum information they need to investigate the bug.

A complete bug report form

name: Bug Report
description: File a bug report
title: "[Bug]: "
labels: ["bug", "needs-triage"]
assignees: []
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!

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

  - type: textarea
    id: expected
    attributes:
      label: Expected Behavior
      placeholder: What did you expect to happen?
    validations:
      required: true

  - type: textarea
    id: actual
    attributes:
      label: Actual Behavior
      placeholder: What actually happened?
    validations:
      required: true

  - type: input
    id: version
    attributes:
      label: Version
      placeholder: "e.g. 2.1.0"
    validations:
      required: false

  - type: textarea
    id: environment
    attributes:
      label: Environment
      placeholder: OS, browser, Node version, etc.

  - type: textarea
    id: screenshots
    attributes:
      label: Screenshots or Logs
      placeholder: Paste any relevant output or drag images here.

Field types and when to use them

Type	Best for
`textarea`	Multi-line free text — reproduction steps, logs, descriptions
`input`	Short single-line values — version numbers, URLs, identifiers
`dropdown`	Constrained choices — severity, component, OS
`checkboxes`	Agreements or multi-select options
`markdown`	Static instructional text that is not submitted with the issue

Tips and notes

Keep at least the reproduction steps and the 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, set blank_issues_enabled: false to force every report through a form rather than allowing a blank issue.