GitHub Issue Form Templates

Overview

GitHub issue form templates are YAML-based forms that replace markdown templates, offering a structured way to collect issue information. Instead of free-form text, issue forms provide:

• Structured fields: Text inputs, dropdowns, checkboxes, textareas, and more

• Validations: Required/optional fields, regex patterns, min/max lengths

• Auto-assignment: Default assignees and labels

• Metadata: Issue types and project assignments

Issue forms are stored in .github/ISSUE_TEMPLATE/ as YAML files (*.yml or *.yaml ).

Quick Start: Creating Your First Issue Form

Basic Structure

Every issue form requires three top-level keys:

name: Bug Report description: File a bug report for our project body:

• type: markdown attributes: value: | Thanks for reporting this bug!

Common Field Types

See Field Types Reference for complete specifications.

Quick examples:

Simple text input

• type: input id: email attributes: label: Email placeholder: you@example.com validations: required: true

Multi-line text

• type: textarea id: description attributes: label: What happened? placeholder: Describe the issue... validations: required: true

Dropdown

• type: dropdown id: severity attributes: label: Severity options: - Critical - High - Medium - Low validations: required: true

Checkboxes

• type: checkboxes id: checklist attributes: label: Checklist options: - label: I've searched existing issues required: true - label: I'm using the latest version

Top-Level Configuration

These keys appear at the root of your YAML file:

Key Type Required Purpose

name

String ✓ Template name shown in issue chooser

description

String ✓ Brief description in template menu

body

Array ✓ Form fields array

title

String

Default issue title (e.g., [Bug]: )

labels

Array/String

Auto-add labels to new issues

assignees

Array/String

Auto-assign users

projects

Array/String

Auto-add to projects (requires IDs)

type

String

Issue type at org level

Example Configuration

name: Bug Report description: File a bug report title: "[Bug]: " labels: ["bug", "triage"] assignees:

• maintainer-username projects:
• org-name/project-number body:

form fields here

Important: The projects field requires write permissions. If contributors lack access, enable auto-add workflows instead.

Field Types by Category

Detailed reference available in Field Types Reference.

Input Types

• markdown - Display-only content (no user input)

• input - Single-line text field

• textarea - Multi-line text field with optional code rendering

• dropdown - Single or multi-select options

• checkboxes - Multiple checkboxes with optional required validation

• hidden - Metadata fields (optional)

Validation Patterns

See Validation Reference for:

• Required field validation

• Regular expression patterns

• Min/max lengths

• Code rendering options

Template Examples

The assets/templates/ directory includes ready-to-use templates:

• bug-report.yml

• Professional bug report form with severity and version tracking

• feature-request.yml

• Feature request template with problem/solution breakdown

• security-vulnerability.yml

• Security issue template with responsible disclosure guidance

Copy and customize these templates for your repository. See Conversion Guide for examples of adapting templates to your needs.

Best Practices

• Lead with validation: Use a checkbox to confirm issue search before continuing

• Progressive disclosure: Start with essential fields, expand advanced options

• Helpful placeholders: Provide examples in placeholders

• Sensible defaults: Pre-select common dropdown options

• Render code blocks: Use render: shell or render: markdown for logs

• Keep it short: Aim for 5-8 fields maximum to reduce friction

• Required wisely: Only make critical fields required

• Test locally: Use GitHub's form preview before committing

Common Issues

GitHub provides validation for issue forms. See Common Validation Errors for:

• Syntax errors

• Invalid field types

• Missing required attributes

• Duplicate IDs

• Schema violations

Workflow: From Markdown to YAML

To convert an existing markdown template to YAML form:

• Extract sections into field entries

• Map markdown sections to appropriate field types

• Add helpful attributes (placeholder, description)

• Add validation rules

• Test the form in GitHub

• Remove old markdown template

See Conversion Guide for a detailed side-by-side comparison and step-by-step conversion process.

How to Verify Your Form Works

After creating your issue form template, verify it functions correctly in GitHub:

Steps to Test

• Commit and push your .yml file to .github/ISSUE_TEMPLATE/ in your repository

• Navigate to Issues tab in your GitHub repository

• Click "New Issue" button

• Verify template appears in the template chooser menu

• Select your template and verify the form renders correctly:

• All fields display with correct labels and descriptions

• Placeholders appear in appropriate fields

• Dropdown options show correctly

• Checkboxes and required fields are marked

• Test field validation:

• Try submitting without filling required fields (should be blocked)

• Test regex validation if applicable (e.g., version format)

• Verify conditional rendering works

• Fill and submit the form to confirm issue creation works as expected

• Check the generated issue to ensure responses are formatted correctly

Troubleshooting Failed Verification

If your template doesn't appear or fails:

• Check Common Validation Errors for YAML syntax issues

• Verify file is in correct location: .github/ISSUE_TEMPLATE/filename.yml

• Ensure YAML frontmatter has required name , description , and body keys

• Try hard-refreshing your browser or opening in private/incognito window

• Check GitHub's issue template documentation for recent changes

Success Indicators

✅ Template appears in issue chooser menu

✅ Form fields render with correct types and attributes

✅ Required field validation prevents empty submissions

✅ Default values and labels display correctly

✅ Regex validation works as expected

✅ Submitted issues contain well-formatted responses

Resources

Reference Files

• Field Types Reference - Complete field type specifications with examples

• Validation Patterns - Validation rules and regex patterns

• Common Validation Errors - Troubleshooting guide

Assets

• templates/

• Ready-to-use template files

• examples/

• Conversion examples and comparisons