GitHub issue template (Markdown)

This template is a Markdown issue template for bug reports. Save it as .github/ISSUE_TEMPLATE/bug_report.md, replace the placeholders, and commit it to the default branch.

Need it as a document? Paste the filled-in template into the free Markdown to Word or Markdown to PDF converter.

Copyable Markdown GitHub issue template

---
name: Bug report
about: Report something that does not work as expected
title: "[Bug]: "
labels: bug
assignees: ""
---

## Summary

[Describe the problem in one or two sentences: what happened, where, and who it affects.]

## Steps to reproduce

1. [Start from a known state, for example a fresh install or a specific page]
2. [Perform one action]
3. [Perform the next action]
4. [Describe what you see]

## Expected behavior

[What should happen.]

## Actual behavior

[What happens instead. Include the exact error message if there is one.]

## Environment

- **Version:** [Release number or commit hash]
- **Operating system:** [Name and version]
- **Browser or runtime:** [Name and version, if relevant]
- **Installation method:** [Package manager, installer, source build, or container]

## Logs and screenshots

```text
[Paste relevant log output here. Remove tokens, passwords, and personal data.]
```

[Attach screenshots or a short screen recording if the problem is visual.]

## Additional context

[Anything else that helps: when the problem started, whether it happens every time, workarounds you found, or related issues.]

## Checklist

- [ ] I searched existing issues and this has not been reported.
- [ ] I can reproduce this on the latest release.
- [ ] This is not a security vulnerability. (Report vulnerabilities as described in SECURITY.md.)

How issue templates work on GitHub

Each file in .github/ISSUE_TEMPLATE becomes one option in the template chooser. The front matter controls how the option appears and what it pre-fills:

Everything below the front matter becomes the issue body. Contributors edit it like any other issue text, so headings and placeholders guide them without forcing a structure.

Most repositories keep several templates side by side, for example bug_report.md, feature_request.md, and documentation.md. The same sections in this template work for a feature request if you replace Steps to reproduce and Expected and Actual behavior with Problem, Proposed solution, and Alternatives considered.

Issue forms: the YAML alternative

Issue forms are YAML files in the same folder that render as a web form with text fields, dropdowns, and checkboxes. Inputs can be marked required, so contributors cannot submit the form without them. GitHub converts the answers into a Markdown issue body. Issue forms are in public preview, and their syntax may change.

An issue form needs name, description, and body. title, labels, assignees, projects, and type are optional.

name: Bug report
description: Report something that does not work as expected.
title: "[Bug]: "
labels: ["bug"]
body:
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Include what you expected to happen instead.
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      placeholder: "For example, 2.4.1"
    validations:
      required: true

Choose a Markdown template when you want free-form issues with light guidance. Choose an issue form when you need specific fields filled in every time, such as a version number.

Configure the template chooser with config.yml

Add .github/ISSUE_TEMPLATE/config.yml to change what the chooser offers:

blank_issues_enabled: false
contact_links:
  - name: Questions and help
    url: https://github.com/[owner]/[repository]/discussions
    about: Ask questions here instead of opening an issue.
  - name: Security vulnerabilities
    url: https://github.com/[owner]/[repository]/blob/main/SECURITY.md
    about: Report vulnerabilities privately as described in our security policy.

With blank_issues_enabled: false, people with Read or Triage access see only your templates. People with Write, Maintain, or Admin access still see a blank issue option marked for maintainers. contact_links sends people to other places, such as discussions or a support site, before they open an issue. The configuration takes effect after it is merged into the default branch.

The legacy single ISSUE_TEMPLATE.md file

Before the template chooser, GitHub supported one issue template per repository: a single issue_template.md file in the repository root, the docs folder, or the .github folder. Because template filenames are not case sensitive, many repositories name it ISSUE_TEMPLATE.md. GitHub Docs describes this as the legacy workflow and recommends the multiple template builder or issue forms instead. If your repository still has a single file, move its content into .github/ISSUE_TEMPLATE/ and add front matter.

Issue template or bug report document?

This page is the repository file that GitHub uses to pre-fill issues. The bug report template is a general bug report document for any tracker, QA handoff, or support escalation, with more detail on severity, reproducibility, and impact. Use this file inside a GitHub repository. Use the bug report document when you report a bug outside GitHub or need a fuller write-up.

Completed issue example

Title: [Bug]: Export to PDF drops images from linked folders

## Summary
PDF export omits images stored outside the document folder.

## Steps to reproduce
1. Open notes/report.md, which links ../images/chart.png.
2. Choose File > Export > PDF.
3. Open the exported PDF.

## Expected behavior
The chart image appears in the PDF.

## Actual behavior
The PDF shows an empty box where the image should be.

## Environment
- Version: 3.2.0
- Operating system: macOS 15.1
- Installation method: installer from the releases page

The example has a specific title, steps that start from a known file, and one observable difference between expected and actual behavior. The product details and version numbers are fictional.

What to include in a GitHub issue template

GitHub issue template FAQ

Where do GitHub issue templates go?

In the .github/ISSUE_TEMPLATE folder on the repository's default branch. Each .md or .yml file in that folder becomes an option in the template chooser.

Can I use one issue template for all my repositories?

Yes. Add the .github/ISSUE_TEMPLATE folder to a public repository named .github in your organization or personal account. GitHub uses it for repositories that have no issue templates of their own. If a repository has any files in its own .github/ISSUE_TEMPLATE folder, none of the default templates are used.

Why does my issue template not appear?

Check that the file is on the default branch, inside .github/ISSUE_TEMPLATE, with a .md or .yml extension, and that the front matter is valid YAML. Quote any value that contains a colon.

Should I use issue forms or Markdown templates?

Use issue forms when specific fields must be filled in, because inputs can be required. Use Markdown templates when you want contributors to write freely with headings as guidance. Issue forms are in public preview.

How do I stop people from opening blank issues?

Add blank_issues_enabled: false to .github/ISSUE_TEMPLATE/config.yml. Users with Write, Maintain, or Admin access can still open a blank issue.

Related templates

• Pull request template
• Bug report template
• SECURITY.md template
• CODE_OF_CONDUCT.md template
• CONTRIBUTING.md template
• README template
• CHANGELOG.md template
• All Markdown templates

Sources

• GitHub Docs: About issue and pull request templates
• GitHub Docs: Configuring issue templates for your repository
• GitHub Docs: Syntax for issue forms
• GitHub Docs: Creating a default community health file
• GitHub Enterprise Server 3.4 Docs: Manually creating a single issue template for your repository (legacy workflow)