What it is: An issue template is a predefined structure that GitHub shows to someone before they create a new issue on a repository — guiding them to fill in specific sections, such as steps to reproduce a bug or the motivation behind a feature request, instead of starting from a completely blank text box.

Why it exists: When anyone can open an issue with no guidance at all, reports naturally end up wildly inconsistent — some overly brief (“it’s broken”), some missing crucial details, some mixing several unrelated problems into one report. An issue template exists to prompt the reporter, at the exact moment they’re writing, for the specific pieces of information the team actually needs to understand and act on the report.

Where it’s used: Issue templates appear on GitHub repositories of every size — a small personal project might use one simple bug-report template, while a large open-source project might offer several different templates (bug report, feature request, documentation issue) so reporters pick whichever matches their situation.

Practical example: A user of an open-source photo-editing tool encounters a crash. Instead of opening a blank issue and writing “it crashed, please fix,” GitHub presents them with a bug-report template asking for the exact steps that led to the crash, the operating system they’re using, and the version of the software installed — information the maintainers would otherwise have to chase down through several back-and-forth comments.

In GitHub’s early years, issues were simply a blank title and a blank description box — completely open-ended. This worked reasonably well for small projects with a handful of contributors who already understood exactly what information mattered. But as open-source projects grew to attract contributors and users who had never interacted with the maintainers before, a predictable pattern emerged: many issues arrived missing exactly the details needed to investigate them, forcing maintainers to spend significant time simply asking follow-up questions before any actual problem-solving could begin.

This back-and-forth wasted time for everyone involved — the reporter had to wait, and the maintainer had to ask, wait, and ask again. Issue templates were introduced specifically to move that information-gathering step earlier, embedding it directly into the reporting process itself so the necessary details show up in the very first message.

The core problem issue templates solve: how do you reliably get the specific information a team needs from someone who may have never reported an issue before, without relying on that person already knowing what to include, and without maintainers having to repeatedly ask the same clarifying questions?

Issue templates are stored as ordinary files inside the repository itself, in a special, reserved folder that GitHub specifically looks for. Because they’re just files in the repository, they’re version-controlled exactly like any other project file — changes to a template go through the same commit history, and can be reviewed through a pull request (as covered in a related guide) just like a code change would be.

There are two supported formats for these files: plain Markdown files with a small block of extra configuration at the top (specifying things like the template’s name and a default title), or a more structured format that lets maintainers define an actual interactive form — with distinct fields, dropdown menus, and checkboxes — rather than just a block of pre-written Markdown text for the reporter to fill in around.

Because a repository can contain more than one template file, GitHub can offer multiple distinct options — a reporter creating a new issue is shown a chooser screen listing every available template, so they can pick whichever one actually matches what they’re trying to report.

flowchart LR
    A["User clicks New Issue"] --> B["GitHub checks the repository's template folder"]
    B --> C{"Any templates configured?"}
    C -->|No| D["Plain blank issue form is shown"]
    C -->|Yes, one| E["That template is shown directly"]
    C -->|Yes, multiple| F["Chooser screen lists all templates"]
    F --> G["User selects the matching template"]
    G --> H["Pre-filled or structured form is displayed"]
    E --> H
    H --> I["User completes the fields and submits"]
    

Step by step, in plain language: first, someone clicks the button to create a new issue on a repository. Second, GitHub checks whether that repository has any template files configured in its reserved folder. Third, if there are none, GitHub simply shows the traditional blank title-and-description box, exactly as it always did before templates existed. Fourth, if exactly one template exists, GitHub shows it immediately; if multiple exist, GitHub first shows a chooser screen listing each one — often with a short description of when to use it — so the reporter picks the option matching their situation. Fifth, once a template is selected, GitHub displays it: either pre-written Markdown headings and prompts the reporter fills in around, or, for the structured form format, distinct labeled fields, dropdowns, and checkboxes the reporter interacts with directly. Finally, the reporter completes the relevant sections and submits, creating a new issue whose content already follows the team’s intended structure.

Notice how the value of a good template compounds: the same handful of upfront questions saves a small amount of back-and-forth on every single issue, and across hundreds or thousands of issues over a project’s lifetime, that adds up to a substantial amount of maintainer time saved.

The original, simpler style is a Markdown-based template: essentially a pre-written issue description containing headings and instructions, like “## Steps to Reproduce” followed by a blank line for the reporter to type under. It’s easy to create and edit, but it relies entirely on the reporter actually following the structure rather than deleting it or ignoring it.

The newer, more structured style — often called a form-based or “YAML” template, named after the configuration format used to define it — lets maintainers define genuinely separate input fields: a dropdown to select which version of the software is affected, a checkbox confirming the reporter searched for existing issues first, or a required text box that can’t be submitted empty. This format enforces structure far more strongly, since the reporter interacts with real form controls rather than freely editable text.

A project doesn’t need every one of these — a small personal project might get by with just a single, simple bug-report template, while a large, high-traffic open-source project may offer several, each carefully tuned for a specific kind of report.

A template can be configured to automatically apply one or more labels — the small, colored tags GitHub uses to categorize issues — the moment an issue is created from it. A bug-report template might automatically add a “bug” label, while a feature-request template automatically adds “enhancement,” saving a maintainer the small but repetitive task of labeling every incoming issue by hand.

Templates can similarly be configured to automatically assign a specific person or team as the default assignee, useful when a particular category of issue — say, anything related to a specific part of the codebase — should always start in front of the same group of people responsible for that area.

The core trade-off to internalize is this: an issue template trades a small amount of one-time design effort — and a small amount of extra friction for the reporter — for a large, ongoing reduction in wasted back-and-forth communication. Getting the balance right means asking for what’s genuinely necessary, and no more.

Because issues on a public repository are visible to anyone, a dedicated security-vulnerability template — as mentioned in Chapter 7 — typically avoids collecting sensitive vulnerability details in a public issue at all. Instead, well-designed security templates redirect the reporter to a private reporting channel, so a genuine, unpatched vulnerability isn’t accidentally broadcast to the public, including to anyone who might exploit it, before the maintainers have had a chance to fix it.

It’s also worth remembering that, like any file in the repository, issue template files themselves go through the same code review process as other changes (covered in a related guide) before being merged — this matters because a form-based template can technically include some interactive behavior, so changes to it deserve the same scrutiny as any other configuration affecting how the project’s public-facing tools behave.

The Minimal-Friction Pattern keeps a template short, asking only for the two or three pieces of information that are almost always needed, trusting maintainers to ask follow-up questions for anything unusual rather than trying to anticipate every possible case upfront.

The Multi-Template Chooser Pattern offers several distinct templates — bug, feature, documentation — each tightly focused on its own category, so reporters aren’t forced to skip irrelevant sections meant for a different kind of report.

The Guided-Checklist Pattern includes checkboxes confirming the reporter has already searched for existing issues or read the contribution guidelines, reducing duplicate reports and reports that don’t match the project’s actual scope.

Common anti-patterns to avoid: the Ignored Template (a Markdown template so easy to delete that most reporters simply erase it and write a single unstructured line instead); the Never-Updated Template (a template that still references an old version numbering scheme or a discontinued product feature, confusing new reporters); and the One-Size-Fits-All Template (using a single bug-report template for feature requests too, forcing awkward, irrelevant answers).

Common mistakes beginners make: copying a generic template from another project without adjusting it to their own project’s actual needs; requiring so many fields that reporters give up partway through; and never revisiting a template after initially setting it up, letting it grow stale as the project changes.