How do I add an issue template to GitHub?

Create the file at .github/ISSUE_TEMPLATE/bug_report.md in your repository. GitHub automatically presents it as a template when contributors open new issues.

Can I have multiple issue templates?

Yes. Add multiple Markdown files to .github/ISSUE_TEMPLATE/ and GitHub shows a template chooser when opening a new issue. Create separate templates for bug reports, feature requests, and questions.

What is the difference between issue templates and issue forms?

Issue forms use YAML to define structured fields (dropdowns, checkboxes, text inputs) that GitHub renders as a form. Markdown templates provide a pre-filled text editor instead.

GitHub Issue Template in Markdown

Well-structured issue templates dramatically improve the quality of bug reports by prompting reporters to include the information maintainers need. This template guides users through the problem description, reproduction steps, expected versus actual behavior, and environment details. The Markdown formatter ensures consistent heading structure and checkbox syntax before you place the file in .github/ISSUE_TEMPLATE/. GitHub renders checkboxes as interactive elements in issues.

Example

## Bug Report

**Describe the bug**
A clear and concise description of what the bug is.

**Steps to Reproduce**

1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Screenshots**
If applicable, add screenshots.

**Environment**

- OS: [e.g. macOS 14, Windows 11]
- Browser: [e.g. Chrome 124, Safari 17]
- Version: [e.g. 2.1.0]

**Additional Context**
Any other context about the problem.

[ open in Markdown Formatter → ]

FAQ

How do I add an issue template to GitHub?: Create the file at .github/ISSUE_TEMPLATE/bug_report.md in your repository. GitHub automatically presents it as a template when contributors open new issues.
Can I have multiple issue templates?: Yes. Add multiple Markdown files to .github/ISSUE_TEMPLATE/ and GitHub shows a template chooser when opening a new issue. Create separate templates for bug reports, feature requests, and questions.
What is the difference between issue templates and issue forms?: Issue forms use YAML to define structured fields (dropdowns, checkboxes, text inputs) that GitHub renders as a form. Markdown templates provide a pre-filled text editor instead.

Related Examples

Pull Request Description Template

A consistent pull request template speeds up code review by ensuring authors inc...

Write a CONTRIBUTING Guide

A contributing guide reduces friction for new contributors by explaining how to ...

Write a Project README in Markdown

A good README is the front door of every open-source project and sets the tone f...