prulloac/github-issue-form-templates

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: [email protected]
  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

1. markdown - Display-only content (no user input)
2. input - Single-line text field
3. textarea - Multi-line text field with optional code rendering
4. dropdown - Single or multi-select options
5. checkboxes - Multiple checkboxes with optional required validation
6. 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

1. Lead with validation: Use a checkbox to confirm issue search before continuing
2. Progressive disclosure: Start with essential fields, expand advanced options
3. Helpful placeholders: Provide examples in placeholders
4. Sensible defaults: Pre-select common dropdown options
5. Render code blocks: Use render: shell or render: markdown for logs
6. Keep it short: Aim for 5-8 fields maximum to reduce friction
7. Required wisely: Only make critical fields required
8. 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:

1. Extract sections into field entries
2. Map markdown sections to appropriate field types
3. Add helpful attributes (placeholder, description)
4. Add validation rules
5. Test the form in GitHub
6. 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

1. Commit and push your .yml file to .github/ISSUE_TEMPLATE/ in your repository
2. Navigate to Issues tab in your GitHub repository
3. Click "New Issue" button
4. Verify template appears in the template chooser menu
5. 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
6. 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
7. Fill and submit the form to confirm issue creation works as expected
8. 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