Skip to main content
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:

​
Key form fields (top-level keys)

This table summarizes common top-level keys you’ll use in issue forms.

​
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.
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.
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.
That’s it — you now have a structured bug report form that enforces consistent bug reporting and accelerates triage.

Watch Video

Practice Lab