Setting Up Issue and Form Templates for Structured Reports
When running a community project, unformatted problem reports often omit the vital facts maintainers need to diagnose problems. By defining structured templates, community administrators can standardize the intake process so contributors submit actionable information from the start. Whether you need open-ended prompts or rigid web forms with required fields, establishing these files in your repository provides consistent guidelines for everyone opening a ticket.
Step 1: Create the Issue Template Directory on the Default Branch
To begin configuring intake paths, you must place your configuration files in the correct directory within your project repository. All issue templates must be stored on your repository's default branch inside a hidden directory named .github/ISSUE_TEMPLATE. As documented in the About issue and pull request templates - GitHub Docs guide, any template created in an alternate branch will not be available for collaborators to select or use.
When setting up the folder structure, note these file requirements:
- Issue template filenames are not case sensitive.
- Standard markdown issue templates require a
.mdfile extension. - Issue templates created as issue forms require a
.ymlfile extension. - Templates can also be deployed across an entire personal account or organization by establishing a default community health file setup, which aligns with repository management strategies covered in our Community Health File Layouts: Profile for Public Project Boards overview.
Step 2: Build Markdown Issue Templates for Flexible Guidance
Markdown templates provide helpful prompts while leaving contributors free to format their responses. You can create these files manually or utilize the built-in issue template builder. When using the builder, you can define a specific title and description for each template, insert the guidance text, and either commit the new file directly to the default branch or open a pull request.
The builder automatically generates the YAML front matter markup that the platform requires to render the template on the ticket submission screen. For a markdown template to display with a checkmark in the repository's community profile checklist, the .md file must reside inside the .github/ISSUE_TEMPLATE directory and contain valid name: and about: keys in its YAML frontmatter.
Step 3: Define Issue Forms to Force Specific Inputs
While standard markdown files allow contributors to alter or delete instructions, issue forms enforce structured problem reporting. Issue forms utilize web form fields built through the GitHub form schema. When a member submits a ticket through an issue form, the platform converts their form inputs directly into a standard markdown issue comment.
Using issue form configuration in a .yml file allows you to:
- Specify different input types to capture exact data categories.
- Designate critical form inputs as required so members cannot submit incomplete support requests.
- Qualify for the community profile checklist checkmark by specifying valid
name:anddescription:keys within the form file.
Restricting incoming problem tickets to mandatory form controls ensures that volunteer teams receive actionable technical details rather than vague bug complaints.
Step 4: Customize the Template Chooser and Direct Sensitive Reports
Once you have multiple templates in place, you can tailor how members select their ticket type. Community maintainers can customize the template chooser interface by adding a config.yml file to the .github/ISSUE_TEMPLATE directory. This configuration dictates how options appear when a contributor initiates a new report.
In addition to standard operational problems, communities frequently need dedicated channels for vulnerability disclosure. Maintainers can publish an explicit security policy to supply clear instructions on how community members should report security vulnerabilities outside of public issue lists.
Step 5: Configure Pull Request Templates for Proposed Fixes
Standardizing intake is equally important when contributors transition from reporting bugs to submitting code or content fixes. According to the About issue and pull request templates - GitHub Docs reference, adding a pull request template ensures contributors automatically see your requested checklist and questions directly in the pull request body.
Pull request templates must also reside on the default branch. However, they offer more flexible placement options than issue forms. You can store your pull request template in the repository's visible root directory, the docs folder, or within the hidden .github directory. The filename is not case sensitive and can carry an extension such as .md or .txt.
Sources
About issue and pull request templates - GitHub Docs
Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.