# GitHub issue templates

> GitHub issue templates are YAML issue forms in .github/ISSUE_TEMPLATE that turn a blank issue into required fields. Copy the three files below into that folder on your default branch, change the labels and links, and the next person who opens an issue picks a form.

Updated November 8, 2026. Canonical: https://sniptide.com/templates/github-issue-templates
Open it in the Sniptide editor: https://app.sniptide.com/new?template=github-issue-templates
Files as JSON: https://sniptide.com/templates/github-issue-templates.json

## Files

### .github/ISSUE_TEMPLATE/bug_report.yml

```yaml
name: Bug report
description: Something doesn't work the way the docs say it should.
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to report this. Please search open issues first, since
        someone may have reported it already.
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: What you did, what you expected and what you saw instead.
      placeholder: I exported invoices to CSV with a date filter, and the file included every invoice.
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      placeholder: |
        1. Open Invoices
        2. Set the date filter to October
        3. Choose Export
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: Shown under Settings > About, or the package version you use.
      placeholder: "2.4.0"
    validations:
      required: true
  - type: dropdown
    id: browsers
    attributes:
      label: Browsers
      description: Where you see the problem. Leave it empty if it isn't browser-specific.
      multiple: true
      options:
        - Chrome
        - Firefox
        - Safari
        - Edge
  - type: textarea
    id: logs
    attributes:
      label: Logs or screenshots
      description: Paste any error output. It's formatted as code automatically.
      render: shell
  - type: checkboxes
    id: terms
    attributes:
      label: Before you submit
      options:
        - label: I searched the open issues and this isn't a duplicate.
          required: true
```

### .github/ISSUE_TEMPLATE/feature_request.yml

```yaml
name: Feature request
description: Suggest something Acme should do that it doesn't yet.
title: "[Feature]: "
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: What problem would this solve?
      description: Describe the situation and what it costs you today. This helps more than a proposed solution.
      placeholder: Every month I export invoices and delete half the rows by hand, because the export ignores my filters.
    validations:
      required: true
  - type: textarea
    id: solution
    attributes:
      label: What would you like to happen?
    validations:
      required: true
  - type: textarea
    id: alternatives
    attributes:
      label: What do you do today instead?
      description: Workarounds you use or other tools you've tried.
  - type: dropdown
    id: frequency
    attributes:
      label: How often do you run into this?
      options:
        - Every day
        - Every week
        - Every month
        - Rarely
    validations:
      required: true
```

### .github/ISSUE_TEMPLATE/config.yml

```yaml
blank_issues_enabled: false
contact_links:
  - name: Questions and help
    url: https://github.com/acme/acme/discussions
    about: Ask how to do something in Discussions, where answers stay findable.
  - name: Security issues
    url: https://acme.com/security
    about: Report vulnerabilities privately. Please don't open a public issue.
```

## Why forms instead of Markdown templates [#why-forms-instead-of-markdown-templates]

GitHub supports two kinds of issue template. A Markdown template pre-fills the issue body, and people delete it. An issue form, the `.yml` files here, shows labeled fields and refuses to submit until the required ones are filled, so every bug arrives with steps and a version. GitHub [documents the syntax](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms) for both.

The files only take effect on the repository's default branch.

## What each file does [#what-each-file-does]

| File | What it does |
| --- | --- |
| `bug_report.yml` | Asks what happened, how to reproduce it and which version, and adds the `bug` and `triage` labels. |
| `feature_request.yml` | Asks for the problem before the solution, and how often it happens, which is what you need to prioritize. |
| `config.yml` | Turns off blank issues and links to Discussions for questions and to a private page for security reports. |

## The fields you'll change [#the-fields-youll-change]

| Key | What it does | Note |
| --- | --- | --- |
| `name`, `description` | The choice people see on the New issue page. | Keep the description to the one case the form is for. |
| `title` | Pre-fills the issue title. | A prefix such as `[Bug]: ` makes the list scannable. |
| `labels` | Labels added on submit. | Create the labels in the repository first. |
| `type` | The field: `markdown`, `textarea`, `input`, `dropdown` or `checkboxes`. | `markdown` shows text and collects nothing. |
| `render` | Formats a `textarea` as a code block. | Use it for logs, so nobody has to add the fences. |
| `validations.required` | Blocks submit until the field is filled. | Require only what you can't triage without. Every extra required field loses reports. |

## Ask for the problem first [#ask-for-the-problem-first]

The feature form asks "What problem would this solve?" before "What would you like to happen?". Requests that start with a solution tend to describe one person's workaround. The problem tells you whether other users share it and whether something you already planned would cover it.

Once an issue is accepted, rewrite it as a [user story](/templates/user-stories) with acceptance criteria before anyone builds it.

## Variant: a pull request template [#variant-a-pull-request-template]

Pull requests use a Markdown file rather than a form. Put it at `.github/pull_request_template.md`:

```md title=".github/pull_request_template.md"
## What this changes

## How I tested it

- [ ] Tests added or updated
- [ ] Docs updated
```