Skip to main content

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 waste time staring at the blank “Description” field and wondering what to write each time you open a pull request, adding a PR template to your repo will speed you up.

By pre-filling your description with consistent prompts, 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:

.github/pull_request_template.md
## ✅ 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. -->
 
## 🔖 Further reading
 
- [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 keeps skipping certain prompts, don’t hesitate to remove them. Only include prompts that actually save everyone time.

If your reviewers always have to ask which ticket each PR relates to, adding a ticket link prompt to the template is probably a good idea. But adding 50 well-intentioned checkboxes will only teach your team to ignore the template entirely.

So, keep it short. 😊

Further reading