GitHub Bug Report Issue Form (YAML)

Building a GitHub Bug Report Issue Form

GitHub issue forms use YAML to define structured forms that replace free-form Markdown issue bodies. A well-designed bug report form captures all the information maintainers need to reproduce and fix issues.

Template Structure

name: "Bug Report"
description: "File a bug report to help us improve"
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for reporting a bug!
  - type: textarea
    id: description
    attributes:
      label: "Describe the Bug"
      description: "A clear description of what the bug is."
    validations:
      required: true
  - type: dropdown
    id: severity
    attributes:
      label: "Severity"
      options:
        - "Critical"
        - "High"
        - "Medium"
        - "Low"
    validations:
      required: true

Key Design Decisions

Structured fields vs. free text: Using dropdowns for severity and environment categories ensures consistent triage data. Textarea fields allow detailed descriptions while keeping the form organized.

Required vs. optional fields: Mark reproduction steps and description as required, but leave screenshots and logs as optional. This balances thoroughness with ease of filing.

Markdown sections: Use markdown body elements to add instructions between form fields, guiding reporters to provide useful information.

File Placement

Save as .github/ISSUE_TEMPLATE/bug-report.yml. GitHub will automatically include it in the issue template chooser when users click "New issue".