When you add an issue template to your repository, project contributors will automatically see the template's contents in the issue form body. Templates customize and standardize the information you'd like included when contributors open issues.

Sample issue template

Contributors and users can use templates to create issues according to the repository's contribution guidelines. For more information, see "Setting guidelines for repository contributors."

You can store your issue template in the repository's visible root directory, the docs folder, or the hidden .github directory. Issue template filenames are not case sensitive, and can have an extension such as .md or .txt.

Tip: You must create your template in your repository's default branch. Templates created in other branches are not available for collaborators to use.

Adding an issue template

  1. On GitHub, navigate to the main page of the repository.

  2. Above the file list, click Create new file. The New file button

  3. In the file name field:

    • To make your issue template visible in the repository's root directory, type the name of your issue_template. For example, issue_template.md. New file name in root
    • To make your issue template visible in the repository's docs directory, type docs/ followed by the name of your issue_template. For example, docs/issue_template.md, New file name in docs directory
    • To store your file in a hidden directory, type .github/ followed by the name of your issue_template. For example, .github/issue_template.md. Hidden directory
  4. In the body of the new file, add your issue template. This could include:
    • Expected behavior and actual behavior.
    • Steps to reproduce the problem.
    • Specifications like the version of the project, operating system, or hardware.
  5. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file. Commit message for your change

  6. Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. If your current branch is master, you should choose to create a new branch for your commit and then create a pull request. Commit branch options

  7. Click Propose new file. Commit new file button

Further reading