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

github-issue-form-templates