Configuring issue templates for your repository

You can customize the templates that are available for contributors to use when they open new issues in your repository.

In this article

You can create default issue templates and a default configuration file for issue templates for your organization. For more information, see "Creating a default community health file for your organization."

Creating issue templates

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

  2. Under your repository name, click Settings.

    Repository settings button

  3. In the "Features" section, under "Issues," click Set up templates.

    Start template setup button

  4. Use the Add template drop-down menu, and click on the type of template you'd like to create.

    Add template drop-down menu

  5. To preview or edit the template before committing it to the repository, click Preview and edit.

    Preview and edit button

  6. To edit the template, click , and type in the fields to edit their contents.

    Issue template edit button

  7. To automatically set a default issue title, assign the issue to people with read access to the repository, or apply labels to your issue template, enter these details under "Optional additional information." You can also add these details in the issue template with title, labels, or assignees in a YAML frontmatter format.

    Additional info for issue template

  8. When you're finished editing and previewing your template, click Propose changes in the upper right corner of the page.

    Propose changes button

  9. Enter a commit message describing your changes.

    Issue template commit message field

  10. Below the commit message fields, decide whether to commit your template directly to the default branch, or to create a new branch and open a pull request. For more information about pull requests, see "About pull requests."

    Issue template commit to master or open pull request choice

  11. Click Commit changes. Once these changes are merged into the default branch, the template will be available for contributors to use when they open new issues in the repository.

Configuring the template chooser

You can customize the issue template chooser that people see when creating a new issue in your repository by adding a config.yml file to the .github/ISSUE_TEMPLATE folder.

You can require contributors to use issue templates by setting blank_issues_enabled to false. If you set blank_issues_enabled to true, people will have the option to open a blank issue.

Note: If you used the legacy workflow to manually create an issue_template.md file and enable blank issues in your config.yml file, the template in issue_template.md will be used when people chose to open a blank issue. If you disable blank issues, the template will never be used.

If you prefer to receive certain reports outside of GitHub, you can direct people to external sites with contact_links.

Here is an example config.yml file.

blank_issues_enabled: false
contact_links:
  - name: GitHub Community Forum
    url: https://github.community/
    about: Please ask and answer questions here.
  - name: GitHub Security Bug Bounty
    url: https://bounty.github.com/
    about: Please report security vulnerabilities here.

Your configuration file will customize the template chooser when the file is merged into the repository's default branch.

  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, type .github/ISSUE_TEMPLATE/config.yml.

    Configuration filename

  4. In the body of the new file, type the contents of your configuration file.

    Configuration file content

  5. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file. You can attribute the commit to more than one author in the commit message. For more information, see "Creating a commit with multiple co-authors."

    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. For more information, see "Creating a new pull request."

    Commit branch options

  7. Click Propose new file.

    Propose new file button

Further reading

Ask a human

Can't find what you're looking for?

Contact us