ContextCapture.
Sign in

Guide

GitHub issue forms guide

Build and install a GitHub issue form that asks reporters for reproduction steps, expected behavior, and supporting evidence.

Install a bug-report form

  1. Download a form below and add it to your repository at .github/ISSUE_TEMPLATE/bug-report.yml. The folder and .yml filename matter.
  2. Commit the file to your repository’s default branch. Open Issues → New issue and select the new form.
  3. Try a report with a required field empty, then submit a complete test issue. Check that the answers appear in the issue body.

GitHub issue forms use YAML with name, description, and body. Form responses become Markdown in the issue. The required-field setting applies to public repositories; check a private repository’s behavior before relying on it. Issue forms do not create pull-request templates.

See GitHub’s installation steps, issue-form syntax, and field validation rules.

Choose a starting form

Builder: checkout failure

A shopper clicks Pay on the checkout page and nothing happens. Ask for the page and browser, the exact steps from cart to Pay, the expected confirmation, the observed result, and a reviewed screenshot or console error.

Create a test issue with the builder form. Leave a required field empty, confirm GitHub blocks submission, then enter a complete report and check the resulting issue body.

Agency or QA: client staging regression

A tester sees a contact form fail only on the client’s staging release in mobile Safari. Put the tested release and client impact in the summary, then add the browser, viewport, repeatable steps, expected confirmation, and actual error. Review screenshots for client or customer details before attaching them.

Create a test issue with the agency form in a client repository. Have another tester follow the steps, compare the issue body across projects, and adjust optional fields that do not help triage.

Check the form before inviting reporters

  • Give each field a useful label and a unique ID. Dropdown options must be distinct and nonempty.
  • Ask for steps, expected behavior, observed behavior, and environment. Keep screenshots and logs optional so a reporter can still submit a useful issue.
  • Review the generated issue, including its title and body, before asking a team to use the form. Remove secrets, customer details, and private URLs from example reports.

If GitHub rejects a form, compare it with the common validation errors. You can also edit the downloaded YAML in your repo. GitHub’s form schema is in public preview and may change.

Need to change field labels or make a Markdown template instead? Use the issue-template builder.

Examples for your team

Builder example

A maintainer installs a bug form in .github/ISSUE_TEMPLATE and checks that required reproduction fields block an empty submission.

Start your 14-day free trial

Agency / QA example

An agency adds tested environment and client impact fields so QA reports from different projects remain comparable.

Start your 14-day free trial

Capture the next report with ContextCapture

Start a 14-day free trial. The beta plan is $7.99 per month for unlimited projects and reports, with up to five team members.

Start your 14-day free trial