> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Demo Developer Workflow Standards Issue Template > Guidance for creating a structured GitHub issue form to collect consistent bug reports with required fields, labels, and YAML formatting for faster triage. In this lesson you will add a structured GitHub issue template so contributors submit consistent, actionable bug reports. A well-crafted template speeds triage, reduces back-and-forth, and captures the environment and reproduction steps maintainers need. Why add an issue form? * Ensures every bug report includes required details (description, reproduction, environment, version). * Lets you pre-assign labels and set default titles to streamline triage. * Renders a guided form in GitHub so contributors don’t have to remember every required field. We already have a pull request template and a `CODEOWNERS` file in the repository. Now we'll add a bug report issue form under the repository's `.github/ISSUE_TEMPLATE/` directory. GitHub detects any `.yml` or `.yaml` files in that folder and renders a friendly form when someone opens a new issue. Place issue forms in `.github/ISSUE_TEMPLATE/` and name them with a `.yml` or `.yaml` extension. Each file must be a valid YAML document describing the form (top‑level keys like `name`, `description`, `title`, `labels`, and `body`). ## Create the file Create a new file at: * `.github/ISSUE_TEMPLATE/bug_report.yml` The following cleaned, complete example produces a user-friendly bug report form with required fields for description, reproduction steps, environment, and version. Copy the YAML into the file you created: ```yaml theme={null} name: "🐞 Bug Report" description: "File a structured bug report to help us improve." title: "[Bug]: " labels: - bug - triage body: - type: markdown attributes: value: | Thanks for taking the time to fill out this bug report! Please provide as much detail as possible. - type: checkboxes id: prerequisites attributes: label: Prerequisites description: Please check the following before submitting your issue. options: - I have searched existing issues to ensure this bug has not already been reported. - I am using the latest stable version of this project. validations: required: true - type: textarea id: description attributes: label: Bug Description description: A clear and concise description of what the bug is. placeholder: Tell us what happened... validations: required: true - type: textarea id: reproduction-steps attributes: label: Reproduction Steps description: Steps to reproduce the bug. placeholder: | 1. Do this 2. Then do that 3. Observe the error validations: required: true - type: dropdown id: environment attributes: label: Environment / Operating System description: Select the environment where you encountered the bug. options: - Windows - macOS - Linux - iOS - Android - Other (specify in Additional Context) multiple: false validations: required: true - type: input id: version attributes: label: Version description: What version of the software are you using? placeholder: e.g., v1.4.2 validations: required: true - type: textarea id: additional-context attributes: label: Additional Context description: Add logs, stack traces, screenshots, or relevant configuration here. placeholder: Error logs, stack traces, or relevant configuration... ``` ## Key form fields (top-level keys) This table summarizes common top-level keys you’ll use in issue forms. | Key | Purpose | Example | | - | - | - | | `name` | Display name of the template in the New Issue UI | `name: "🐞 Bug Report"` | | `description` | Short description shown under the template name | `description: "File a structured bug report..."` | | `title` | Default title prefix for new issues | `title: "[Bug]: "` | | `labels` | Default labels applied to issues created from this form | `labels: ["bug", "triage"]` | | `body` | Array describing form inputs and markdown sections | See the YAML example above for `type`, `id`, `attributes`, and `validations` | ## How it looks in GitHub After committing the file to the repository’s default branch (for example, `main`), GitHub will surface this template in the New Issue dialog. The preview below shows the repository file tree and the issue template file in the editor. ![Screenshot of a GitHub repository page in dark mode showing the .github/ISSUE\_TEMPLATE/bug\_report.yml file preview and the repository file tree at left. The page displays a bug report issue form template with sections like Prerequisites and Bug Description.](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Governance-and-Roles/Demo-Developer-Workflow-Standards-Issue-Template/github-issue-template-bug-report-screenshot.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=e057be91b02b4a0df6b5efc7a1adf4a1) When a contributor clicks New Issue, they’ll see available templates. Selecting the Bug Report template displays the structured fields you defined — description, reproduction steps, environment, version, etc. GitHub will also apply the default title and labels from the YAML. You can fill out the fields, pick an environment (for example, `iOS`), add a version, paste logs, and then submit. The issue page also shows standard metadata in the sidebar (assignees, labels, projects, milestones) which maintainers can set or update. ![A dark‑mode screenshot of a GitHub repository issue page showing a bug report titled “\[Bug\]: test1 #2,” with the issue content and checklist on the left and the assignees/labels/fields sidebar on the right.](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Governance-and-Roles/Demo-Developer-Workflow-Standards-Issue-Template/github-issue-bug-test1-dark-screenshot.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=32a251da6c78d20bf2acc7a89b7e7919) Common pitfalls: * Ensure the folder path is exactly `.github/ISSUE_TEMPLATE/` (no typos, correct capitalization). * File names must end with `.yml` or `.yaml`. * Validate your YAML syntax before committing — an invalid YAML file may prevent GitHub from rendering the form. ## Commit and verification 1. Add the file to your branch and commit: `git add .github/ISSUE_TEMPLATE/bug_report.yml && git commit -m "Add bug report issue template"`. 2. Push the commit to the default branch (for example, `main`): `git push origin main`. 3. Visit the repository, click New Issue, and confirm the Bug Report template appears and renders the expected fields. ## Tips for maintainers * Keep required fields minimal but essential — too many required inputs can discourage useful reports. * Use checkboxes for pre-submission checks (e.g., "I’ve searched existing issues"). * Include a `Additional Context` textarea to collect logs or attachments. * Add default `labels` (like `bug`, `triage`) so maintainers can quickly filter new reports. ## Links and references * [GitHub: About issue templates](https://docs.github.com/en/issues/creating-closing-and-reopening-issues/managing-issues/about-issue-and-pull-request-templates) * [GitHub: Creating issue forms](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-issues/about-issue-forms) * YAML validator: [https://yamlchecker.com](https://yamlchecker.com) That's it — you now have a structured bug report form that enforces consistent bug reporting and accelerates triage. > [card] [Watch Video](https://learn.kodekloud.com/user/courses/github-administration-certification/module/e4b7bd78-3fb5-4c1c-94d8-e528b0b60484/lesson/97e59a14-b47e-4f69-954e-767ef8135892) > [card] [Practice Lab](https://learn.kodekloud.com/user/courses/github-administration-certification/module/e4b7bd78-3fb5-4c1c-94d8-e528b0b60484/lesson/5bfa4bd3-3f8d-4127-b962-14164a7d5fac) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.