GitHub Templates: PR, Issue & Discussion Best Practices

Amaresh Pelleti
GitHub pull request template example

GitHub templates pre-fill new pull requests, issues and discussions so contributors give you the details you need up front. Pull request templates are Markdown. Issues can use Markdown templates or YAML issue forms. Discussions only support YAML forms. All of them live in the .github/ folder of your repository.

This guide shows working examples of each, where the files go, and the mistakes that stop them from appearing. Part of our complete Git and GitHub Actions guide. Pair templates with CODEOWNERS so the right people review what comes in.

Where Each Template Goes

TemplateFormatPath
Pull request (single)Markdown.github/pull_request_template.md
Pull request (several)Markdown.github/PULL_REQUEST_TEMPLATE/*.md
Issue templateMarkdown with front matter.github/ISSUE_TEMPLATE/*.md
Issue formYAML.github/ISSUE_TEMPLATE/*.yml
Issue chooser settingsYAML.github/ISSUE_TEMPLATE/config.yml
Discussion formYAML only.github/DISCUSSION_TEMPLATE/<category-slug>.yml

Templates must be on the repository’s default branch to take effect. A template sitting on a feature branch does nothing.

Pull Request Templates

Create .github/pull_request_template.md. GitHub loads it into the description of every new pull request:

## What changed and why


Closes #

## How it was tested


## Checklist
- [ ] Tests added or updated
- [ ] Docs updated if behavior changed
- [ ] No secrets or credentials in the diff

Closes #123 in the body automatically closes that issue when the PR merges into the default branch.

Multiple PR templates

Put several files in .github/PULL_REQUEST_TEMPLATE/, for example feature.md and hotfix.md. GitHub does not show a chooser for these. You pick one with the template query parameter when opening the compare page:

https://github.com/<owner>/<repo>/compare/main...my-branch?template=hotfix.md

Because of that, most teams keep one default template and use the folder only for special cases they link to from their docs.

Issue Forms (Recommended)

Issue forms render real input fields, dropdowns and checkboxes, and can make fields required. You get consistent, complete bug reports instead of a Markdown template that people delete. Save this as .github/ISSUE_TEMPLATE/bug_report.yml:

name: Bug report
description: Report something that is broken
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Include the exact error message if there is one.
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      placeholder: |
        1. Run ...
        2. See error
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      placeholder: v2.3.4
    validations:
      required: true
  - type: dropdown
    id: os
    attributes:
      label: Operating system
      options:
        - Linux
        - macOS
        - Windows
  - type: checkboxes
    id: checks
    attributes:
      label: Before submitting
      options:
        - label: I searched existing issues
          required: true

Markdown issue templates

The older format still works and is fine for simple cases. Save as .github/ISSUE_TEMPLATE/feature_request.md:

---
name: Feature request
about: Suggest an idea
labels: enhancement
---

## Problem
What problem does this solve?

## Proposed solution

## Alternatives considered

Control the issue chooser

.github/ISSUE_TEMPLATE/config.yml lets you turn off blank issues and send questions elsewhere:

blank_issues_enabled: false
contact_links:
  - name: Questions and help
    url: https://github.com/<owner>/<repo>/discussions
    about: Ask questions in Discussions instead of opening an issue.

Discussion Category Forms

Discussions support YAML forms only, not Markdown templates. The file name must match the slug of an existing discussion category. For an “Ideas” category, create .github/DISCUSSION_TEMPLATE/ideas.yml:

title: "[Idea] "
labels: ["idea"]
body:
  - type: textarea
    id: problem
    attributes:
      label: What problem does this solve?
    validations:
      required: true
  - type: textarea
    id: proposal
    attributes:
      label: Proposed solution

Discussion forms are not supported for polls.

Share Templates Across an Organization

Create a public repository named .github in your organization and put your templates in it. Any repository in the org that has no templates of its own will use these as defaults. A repository’s own templates always override the org defaults.

Example Layout

.github/
├── pull_request_template.md
├── ISSUE_TEMPLATE/
│   ├── bug_report.yml
│   ├── feature_request.md
│   └── config.yml
└── DISCUSSION_TEMPLATE/
    └── ideas.yml

Best Practices

  • Keep them short. Every extra field is a reason for someone not to report the bug.
  • Require only what you need to act: what happened, how to reproduce, which version.
  • Apply labels automatically in the template so triage starts sorted.
  • Send questions to Discussions with config.yml so issues stay actionable.
  • Revisit templates when you notice the same follow-up question on every issue. That question belongs in the form.

Troubleshooting

  • Template not showing: it is not on the default branch, or the file name or folder is misspelled (folder names like ISSUE_TEMPLATE are case sensitive).
  • Issue form shows an error banner: the YAML is invalid. Each field needs a unique id, and every dropdown needs options.
  • Discussion form ignored: the file name does not match the category slug, or it is a .md file.
  • Multiple PR templates never appear: expected. Use the ?template= query parameter.

Frequently Asked Questions

Where do GitHub issue and pull request templates live?

In the .github folder of your repository: .github/PULL_REQUEST_TEMPLATE.md for PRs, and .github/ISSUE_TEMPLATE/ for one or more issue templates.

Can I have more than one issue template?

Yes. Put multiple Markdown or YAML form files in .github/ISSUE_TEMPLATE/ and add a config.yml to control the chooser and any external links.

What is the difference between issue templates and issue forms?

Templates are plain Markdown that pre-fills the issue body; forms are YAML that render structured fields and can require input before the issue is submitted.

Do templates apply to existing issues and PRs?

No. They only pre-fill new issues and pull requests. Existing ones are unchanged.

You Might Also Like