GitHub feature request issue templates

A GitHub issue template is a YAML file that GitHub renders as a structured form instead of a blank text box, so every reporter fills in the same fields in the same order. Below is a complete feature request form you can copy, the field types explained, a matching bug report form, and the config file that adds contact links or turns off blank issues entirely.

Where do issue template files go?

Every template lives in .github/ISSUE_TEMPLATE/ at the root of your repository, one YAML file per template.

.github/
  ISSUE_TEMPLATE/
    feature_request.yml
    bug_report.yml
    config.yml

GitHub reads every .yml file in that folder and offers each one as an option when someone clicks "New issue". The config.yml file in the same folder controls what sits alongside those options, covered below.

What does a complete feature request form look like?

name: Feature request
description: Suggest an idea for this project
title: "[Feature]: "
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: What problem does this solve?
      description: What are you trying to do that the product does not support?
      placeholder: I'm always frustrated when...
    validations:
      required: true
  - type: textarea
    id: solution
    attributes:
      label: What would you like to happen?
      description: A clear description of the change you would like to see.
    validations:
      required: true
  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives you've considered
      description: Other ways you have tried to solve this, or your workaround.
    validations:
      required: false
  - type: dropdown
    id: priority
    attributes:
      label: How much does this affect you?
      options:
        - Nice to have
        - Would use it regularly
        - Blocking my work
    validations:
      required: true
  - type: checkboxes
    id: terms
    attributes:
      label: Checks
      options:
        - label: I searched existing issues before opening this one
          required: true

What does each field type actually do?

GitHub's issue forms support a small set of field types, and each behaves differently once it renders.

• input: a single-line box, for a short value like a version number or a URL. Use it when the answer should never wrap to a second line.
• textarea: a multi-line box, for anything that needs explaining. Most of the substance in a feature request form sits in textarea fields.
• dropdown: a fixed list of options the reporter picks from, so answers are consistent enough to filter or sort by later. Set multiple: true if more than one option can apply at once.
• checkboxes: one or more tick boxes, each with its own required: true or false. Useful for a short confirmation, like agreeing the reporter searched existing issues first, rather than for open-ended input.
• markdown: static text with no input at all, for instructions or context at the top of the form. It doesn't take an id because it never produces an answer.

A few attributes apply across most of these:

• id: the field's internal name, used if the form's answers are ever read by automation such as a bot that labels issues based on the dropdown value.
• label: the question shown to the reporter.
• description: a smaller line under the label, for guidance the label alone doesn't cover.
• placeholder: greyed-out example text inside an empty input or textarea.
• validations: required: blocks submission until the field is filled in or a required checkbox is ticked, which is the one thing a plain text box on its own cannot do.

What does a matching bug report form look like?

name: Bug report
description: File a bug report
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Tell us what you expected and what happened instead.
      placeholder: I expected X, but Y happened instead.
    validations:
      required: true
  - type: textarea
    id: reproduce
    attributes:
      label: Steps to reproduce
      description: A numbered list, starting from a known point.
      placeholder: |
        1.
        2.
        3.
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: Which version were you running?
      placeholder: v1.2.3
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Relevant log output
      description: This is automatically formatted as code, no backticks needed.
      render: shell
    validations:
      required: false

For a longer walkthrough of bug-specific templates, including a crash-focused version, see a feature request template you can copy, which covers the equivalent territory for feature requests.

What does config.yml control?

config.yml sits in the same .github/ISSUE_TEMPLATE/ folder and isn't a form itself. It controls the page a reporter sees before choosing a template: whether a blank issue is still allowed, and what extra links appear alongside the templates.

blank_issues_enabled: false
contact_links:
  - name: Ask a question
    url: https://github.com/your-org/your-repo/discussions
    about: Please use Discussions for questions rather than the issue tracker.
  - name: Security vulnerability
    url: https://github.com/your-org/your-repo/security/policy
    about: Please report security issues privately rather than as a public issue.

• blank_issues_enabled: false: removes the option to open an issue with no template at all, which forces every report through one of the structured forms instead of a free-text box.
• contact_links: each entry adds a button that sends the reporter somewhere other than a new issue, commonly a Discussions board for questions or a private channel for security reports, so the issue tracker stays for actual bugs and feature requests.

Where does this approach fall short?

Issue forms are a good fit for a developer-facing project and a poor fit for a consumer product, for three reasons that don't show up until people actually try to use one.

First, posting requires a GitHub account. Most buyers of a consumer app do not have one and are not going to create one just to leave a suggestion, which quietly filters out the majority of your actual audience before a single form field matters.

Second, reactions on an issue are not votes. A thumbs-up emoji feels like a vote, but nothing about GitHub's issue tracker sorts, ranks or surfaces issues by reaction count, so the loudest or oldest thread wins by default rather than the most-wanted one.

Third, every complaint filed this way is public, permanent, and indexed against your product name. A frustrated bug report or a blunt "this is missing" issue sits on the open web next to your repository forever, discoverable by anyone searching your product's name, in a format built for developers rather than customers.

None of this makes issue forms wrong. For an open source project or a developer tool where your users already live on GitHub, this is close to the best structured intake you can build for free. For a consumer product, a dedicated feature request board that doesn't require a GitHub account is the better fit; see feature request tools for what that looks like.

Frequently asked questions