← all posts
GitHub workflow

GitHub Issue Templates: A Complete Guide (Plus What They Can't Do)

Aalex r. · engineering · 5 min · jul 2026

GitHub issue templates save you from the blank-text-box problem: bug reports arrive with reproduction steps, feature requests arrive with motivation, RFCs arrive with a consistent structure. Here's how to set them up — and the structural limit that no amount of YAML will get you past.

Markdown templates (the simple version)

Create a .github/ISSUE_TEMPLATE/ directory in your repo. Add a markdown file for each template.

.github/ISSUE_TEMPLATE/bug_report.md:

---
name: Bug Report
about: Report a bug in the project
title: "[BUG] "
labels: bug
assignees: ''
---
 
## Describe the bug
 
A clear description of what the bug is.
 
## Steps to reproduce
 
1. Go to '...'
2. Click on '...'
3. See error
 
## Expected behavior
 
What you expected to happen.
 
## Environment
 
- OS: [e.g. macOS 14.1]
- Browser: [e.g. Chrome 120]
- Version: [e.g. 2.3.1]

When someone clicks "New Issue" and selects this template, the markdown pre-fills the issue body. They replace the placeholder text with their details.

Pros: Dead simple. Works immediately. No YAML to learn.

Cons: Nothing is enforced. People can (and will) delete sections, leave placeholders unchanged, or ignore the structure entirely. It's a suggestion, not a form.

YAML form templates (the enforced version)

GitHub also supports YAML-based issue forms with actual form fields — text inputs, dropdowns, checkboxes. These are enforced: required fields must be filled out before the issue can be submitted.

.github/ISSUE_TEMPLATE/bug_report.yml:

name: Bug Report
description: Report a bug in the project
title: "[BUG] "
labels: ["bug"]
body:
  - type: textarea
    id: description
    attributes:
      label: Describe the bug
      description: A clear description of what the bug is.
    validations:
      required: true
 
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      description: Step-by-step instructions to reproduce the issue.
      placeholder: |
        1. Go to '...'
        2. Click on '...'
        3. See error
    validations:
      required: true
 
  - type: dropdown
    id: severity
    attributes:
      label: Severity
      options:
        - Critical (blocks work)
        - Major (significant impact)
        - Minor (inconvenience)
        - Cosmetic
    validations:
      required: true
 
  - type: input
    id: version
    attributes:
      label: Version
      description: What version are you running?
      placeholder: "e.g. 2.3.1"
    validations:
      required: true
 
  - type: textarea
    id: environment
    attributes:
      label: Environment
      description: OS, browser, and any relevant details.
    validations:
      required: false

Available field types:

  • input — single-line text
  • textarea — multi-line text
  • dropdown — select from options
  • checkboxes — multiple selection
  • markdown — static text (for instructions, not user input)

Template chooser config

You can also add a config.yml to control what people see when they click "New Issue":

.github/ISSUE_TEMPLATE/config.yml:

blank_issues_enabled: false
contact_links:
  - name: Feature Request
    url: https://github.com/org/repo/discussions/new?category=ideas
    about: Suggest a feature in Discussions
  - name: Question
    url: https://github.com/org/repo/discussions/new?category=q-a
    about: Ask a question in Discussions

Setting blank_issues_enabled: false forces people to pick a template. No more blank issues with "it's broken" and nothing else.

The contact_links option lets you redirect certain categories elsewhere — like sending feature requests to Discussions instead of Issues.

Tips for good templates

Keep templates short. Every required field is friction. A bug report needs reproduction steps, expected vs. actual behavior, and version. It doesn't need the user's life story.

Use dropdowns for categorical data. Severity, priority, affected component — anything with a fixed set of options should be a dropdown. It's faster to fill out and easier to filter.

Make the critical fields required, the rest optional. Required: description, reproduction steps, version. Optional: screenshots, environment details, related issues. If everything is required, people will type "N/A" in half the fields.

Write good placeholder text. Placeholders show people what a good response looks like. "e.g. When I click the submit button on the settings page, I get a 500 error" is better than "Describe what happened."

Add a markdown section at the top with instructions. A brief "Thank you for reporting a bug. Please fill out the fields below so we can reproduce and fix it." sets expectations.

What templates can do

Templates solve the input problem. When someone opens an issue, they know what information to provide and in what format. This is genuinely valuable:

  • Bug reports have reproduction steps
  • Feature requests have context and motivation
  • RFCs follow a consistent structure
  • Support requests include the right diagnostic info

Without templates, you spend half your triage time asking "what version are you on?" and "can you share the error message?" Templates front-load that information.

Templates structure the ask. Nothing structures the answer.

Templates govern the input — what goes into the issue. They do nothing for the response — what comes back.

Once the issue is open, the feedback mechanism is a comment thread, with everything that implies. You can't:

  • Ask reviewers specific questions and see their answers organized by question
  • Require input from specific people
  • Set a review deadline
  • Collect structured responses (choose from options, rate something, answer yes/no)
  • Share the issue with someone who doesn't have GitHub access

This doesn't matter for bug reports. Someone reports a bug, you fix it, you close the issue. The comment thread is fine.

It matters a lot for proposals, RFCs, and decisions. (If you're routing those through your tracker, first check whether an issue is even the right container.) You create an issue with a perfectly structured template, and then the response process is a free-for-all. The template gives you a great document and a terrible feedback loop.

Closing the loop

If your issues are proposals that need structured feedback, Inkling picks up where templates leave off.

You paste the GitHub issue URL — template and all — and add questions inline. The questions are the response template: instead of freeform comments, reviewers answer specific questions tied to specific sections of the proposal. You can share the link with people who don't have repo access. Responses come back structured.

GitHub issue templates handle the input. Inkling handles the response.

Try Inkling free →

← back to all posts