How to add a PR template to your GitHub repo

Updated 5 months ago

A blank, white page in a spiral-bound notebook with a sharpened pencil laying on it.

If you spend time wondering what to write in the blank “Description” field every time you open a pull request, adding a PR template to your repo will speed you up.

By pre-filling that “Description” field with a few quick prompts to answer, you’ll always know what to write and your reviewers will always get the info they need.

How to add a PR template

  1. Create a folder called .github at the root of your repo
  2. Create a file called .github/
  3. Use GitHub’s Markdown syntax to add any prompts you think will be useful to that file

That’s it! Each time you open a pull request, the description section will now be pre-filled with your template.

What to include in your template?

Feel free to add any prompts you like! I prefer to keep it simple:

## ✅ What

<!-- A brief description of the changes in this PR. -->

## 🤔 Why

<!-- A brief description of why we want these changes. -->

## 👩‍🔬 How to test

<!-- Step-by-step instructions for verifying these changes work as expected. -->

## 🔖 Related links

- [Jira task](<!-- link -->)
- [Slack thread](<!-- link -->)

(Those comments are only visible while editing.)

Don’t overdo it

Whatever you do, don’t make your PR template too long. If you notice your team generally skips certain prompts, don’t hesitate to remove them.

Only include prompts that actually save everyone time. If your reviewers consistently ask which ticket your PRs relate to, adding a ticket link prompt to the template is probably a good idea. But adding 50 well-intentioned checkboxes will only cause your team to skip the template entirely.

So, keep it short. 😊

Related links