How to Create Issue Forms in GitHub (YAML Templates for Bugs and Requests)
Markdown issue templates are better than nothing, but people delete the headings and write a single sentence. GitHub issue forms fix that by turning templates into real forms with text inputs, dropdowns, checkboxes, and required fields. The submitted issue is still Markdown, but the information you need is guaranteed to be there.
This guide covers creating issue forms in the .github/ISSUE_TEMPLATE directory, choosing field types, applying default labels and assignees, and adding a config file that controls the template chooser. It is useful for open-source maintainers and for internal teams using GitHub Issues as their tracker.
Working in GitHub? Turn your spec into dependency-ordered tickets.
Paste the feature or spec. Vantage pulls out the requirements and breaks them into tickets, ordered by what blocks what, ready to groom with your team.
How this works
- We save what you typed. No AI runs on this page.
- You create a free account.
- Vantage builds a PRD and dependency-ordered tickets from it inside your own workspace.
Why ask for an account? We’re a small team, and a full generation runs a multi-step AI pipeline that costs us real money. So we tie it to a free account instead of running it anonymously. You also get to keep the result and edit it.
Your text is only used to create your project, and it stays private to your account. If you don’t sign up, we delete it after 7 days. Privacy policy
Step-by-step guide
Create the template directory
Issue forms live in the .github/ISSUE_TEMPLATE directory on the repository's default branch. Each form is a YAML file, such as bug_report.yml. Templates must be on the default branch to appear in the chooser.
- Create .github/ISSUE_TEMPLATE in the repository
- Add one YAML file per form
- Merge to the default branch to make forms available
Define the form metadata
At the top of each file, set name and description, which appear in the template chooser. Optionally set a default title prefix, labels, and assignees. For a bug form, a title such as '[Bug]: ' and a 'bug' label make triage and filtering easier.
- Set name and description for the chooser
- Add a title prefix to make issue types obvious in lists
- Add labels so issues are categorized on creation
- Add assignees only if one person or team always triages this type
Add fields to the body
The body is a list of elements. Available types include markdown (static text for instructions), input (single line), textarea (multi-line, optionally rendered as code), dropdown (single or multiple choice), and checkboxes. Each input element has an id and attributes such as label, description, and placeholder.
- Use a markdown element at the top to explain what makes a good report
- Use textarea for steps to reproduce and expected versus actual behavior
- Use dropdown for severity, platform, or area
- Use checkboxes for confirmations such as 'I searched existing issues'
Make critical fields required
Add validations with required: true to fields you cannot work without, such as reproduction steps. Be selective. Requiring every field frustrates reporters and leads to filler text. Two or three required fields is usually enough.
Add a config file for the template chooser
Create .github/ISSUE_TEMPLATE/config.yml to control the chooser. Set blank_issues_enabled to false if you want every issue to use a form. Add contact_links to route questions to Discussions, a support portal, or documentation, so the issue tracker stays focused on actionable work.
Create a feature request form
A good feature request form asks for the problem first, then the proposed solution, then alternatives considered. Add a dropdown for who is affected, such as admins or end users. Framing the form around problems gives PMs better input for prioritization than a list of feature names.
Test the forms and iterate
Open the new issue page and walk through each form. Check that labels apply and the rendered Markdown reads well. After a few weeks, review submitted issues and remove fields that are consistently unhelpful.
Common mistakes
Forms not on the default branch
Forms on a feature branch do not appear in the chooser. Merge them to the default branch.
Requiring too many fields
Every required field adds friction. If reporters are filling in 'n/a' everywhere, relax the requirements.
Invalid YAML
Indentation errors or unknown keys can stop a form from rendering. Validate the YAML and check the template chooser after each change.
Tips
Use dropdowns for structured data you want to filter on later, such as platform or area.
Include a link to your severity definitions in the bug form's markdown element.
Disable blank issues once your forms cover the common cases.
Route support questions to Discussions using contact_links to keep the tracker clean.
How Vantage helps
Issue forms improve what comes in from reporters. Vantage helps PMs turn that signal into decisions: bring issues and feedback in as context, write a PRD grounded in the evidence, and generate dependency-aware tickets that push to Linear or Jira with bi-directional sync.