GitHub Issue and Pull Request Templates in Markdown: A Practical Setup

Quick answer

An issue template is a Markdown file (or a YAML issue form) inside .github/ISSUE_TEMPLATE/. A pull request template is a single file named PULL_REQUEST_TEMPLATE.md, and it can live in your repo's root, in a docs folder, or in the hidden .github directory. Both work the same way once they're set up: GitHub auto-populates the body with the template's contents the moment someone opens a new issue or PR, so contributors start from a consistent structure instead of a blank box.

That matters more than it sounds like it should. A bug report missing repro steps or a PR with no description costs you a round of back-and-forth before you can even start reviewing. A template closes that gap for free — no bot, no plugin, just a file committed to the repo.

Below: exactly where each file goes, the frontmatter it needs, how to run more than one template with a chooser, and the couple of things that trip people up the first time.

Step-by-step

Add a single issue template

Create .github/ISSUE_TEMPLATE/bug_report.md and start it with YAML frontmatter:

---
name: Bug report
about: Report something that isn't working
title: "[Bug]: "
labels: bug
---

name and about are the two keys GitHub checks. Skip them and the template won't register correctly or show the checkmark on your repo's community profile. title, labels, and assignees are optional but worth setting — they prefill the new issue so every bug report starts the same way.

Below the frontmatter, write the body exactly like you'd write any other Markdown file — headings for each section you want filled in, a checklist for reproduction steps, a fenced code block for stack traces or logs. This is also the natural place to point contributors at a CONTRIBUTING.md people will actually follow: the CONTRIBUTING doc tells people when and how to open an issue; the template controls what ends up in it once they do.

Add a pull request template

A pull request template is simpler — one file, no frontmatter required. Name it PULL_REQUEST_TEMPLATE.md (filenames aren't case-sensitive, and .txt also works) and put it in the repo's visible root, in a docs folder, or inside .github. Once it's committed, its contents automatically fill the PR body every time someone opens a new pull request against that repo.

A short, useful template is usually three sections: what changed, why, and how you tested it. Don't over-engineer it — a template nobody fills in honestly is worse than no template.

Support multiple templates with a chooser

Once you have more than one kind of issue — a bug report and a feature request, say — add both files to .github/ISSUE_TEMPLATE/ and prefix the filenames with numbers to control the order contributors see them in:

.github/ISSUE_TEMPLATE/
  1-bug.yml
  2-feature-request.yml
  config.yml

(Past nine templates, zero-pad the prefixes — 01-, 02-, up through 11- — so the sort stays numeric instead of alphabetical.)

config.yml in that same folder controls the chooser itself. Two keys do the real work: blank_issues_enabled: false removes the "open a blank issue" option for most contributors (anyone with write access or higher keeps it regardless), and contact_links redirects specific kinds of reports — a support question, say — to an external resource like a discussions board instead of an issue:

blank_issues_enabled: false
contact_links:
  - name: Ask a question
    url: https://github.com/orgs/your-org/discussions
    about: Please ask and answer questions here.

Format the template body for clarity

Inside either template, plain Markdown formatting does a lot of work: a task list for a repro checklist, a fenced code block for logs, and — on GitHub specifically — the NOTE, TIP, and WARNING alert syntax is a clean way to call out a required field ("NOTE: include your OS version") without writing a whole extra paragraph.

Commit to the default branch

This is the step that catches people: a template only becomes visible to other collaborators once it's committed to the repository's default branch. Add it on a feature branch and test it yourself all you want — nobody else will see it until it's merged.

Common problems and fixes

"My template isn't showing up." Check three things in order: the file lives inside .github/ISSUE_TEMPLATE/ (not just .github/), the frontmatter has the required name and about keys, and the branch you committed to is the repo's default branch. Any one of those being wrong is enough to hide the template.

Markdown template or issue form — which one? An issue form is a YAML file that renders as a structured web form — dropdowns, required checkboxes, a text field with a code-block renderer — and converts to a single Markdown comment once submitted. It trades the free-text flexibility of a plain Markdown template for consistently structured data. A lot of repos run both: an issue form for bug reports, where every field genuinely needs to be filled in the same way, and a plain Markdown template for open-ended feature requests where a rigid form would just get in the way.

Templates that quietly go stale. A template nobody revisits drifts from how the project really works. README badges and a CONTRIBUTING doc have the same problem if nobody owns them. Worth a five-minute check the next time you update your contributing guidelines: does the bug report template still ask for the right information?

Doing this with Carets

Issue templates and pull request templates are just Markdown and YAML files sitting in a repo. That makes editing .github/ISSUE_TEMPLATE/bug_report.md or PULL_REQUEST_TEMPLATE.md from your phone between meetings exactly the kind of quick edit Carets is built for. It's a native, fast editor for iPhone, iPad, and Mac, with syntax highlighting for the YAML frontmatter — so a typo in name: or about: is easy to spot before you commit.

Carets also organizes work into files, projects, and tags, which means you can keep a small library of reusable template snippets — a bug-report skeleton, a PR checklist — and drop the pieces you need into a new repo instead of writing them from scratch each time.

Carets is available on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

Do issue and pull request templates have to be Markdown files?

Issue templates are plain Markdown (.md) files by default, and pull request templates are always Markdown or plain text (.md or .txt) — there's no alternative format for PR templates. Issue templates have one alternative: issue forms, which use YAML (.yml) instead of Markdown and render as a structured web form, but they still convert to a single Markdown comment once submitted.

Where do issue and pull request templates need to live in the repo?

Issue templates (both Markdown and YAML issue forms) go in .github/ISSUE_TEMPLATE/. Pull request templates are more flexible — the repo's visible root, a docs folder, or the hidden .github directory all work, as long as the filename is PULL_REQUEST_TEMPLATE with a .md or .txt extension. Either way, the template has to be committed to the default branch, or collaborators won't see it.

What's the minimum frontmatter an issue template needs?

A Markdown issue template needs name: and about: in its YAML frontmatter to register correctly and show up with a checkmark on the community profile checklist. An issue form needs name: and description: instead. Optional keys on either — title, labels, assignees — prefill the new issue so contributors start from a consistent baseline.

How do I control the order when I have more than one issue template?

GitHub lists templates in the chooser by filename, so a numeric prefix like 1-bug.yml and 2-feature-request.yml sets the order you want. Once you're past nine templates, zero-pad the prefixes (01-, 02-, ... 11-) so the sort stays numeric instead of alphabetical.

Conclusion

Issue and pull request templates aren't a GitHub feature you configure through a settings page — they're just Markdown and YAML files in specific folders, with a couple of required frontmatter keys. Start with one issue template and one pull request template. Add the config.yml chooser once you have more than one kind of issue to route, not before.