Adding a Pull Request Template to Your GitHub Repo

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

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/pull_request_template.md
  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 the reason for these changes. -->

## 👩‍🔬 How to validate

<!-- Step-by-step instructions for how reviewers can verify these changes work as expected. -->

## 🔖 Related links

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

(The 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. 😊

Further reading