How-To2026-09-059 min read

How to Set Up Pull Request Templates in GitHub

Pull request templates eliminate the most common code review bottleneck: missing context. When a reviewer opens a PR and sees only a title and a diff, they spend time figuring out what the change does before they can evaluate whether it does it correctly. A well-designed template ensures every PR ships with the why, the what, and the how-to-test baked in.

GitHub supports both a single default template and multiple templates for different change types. This guide covers setting up both, from a general-purpose template that works for most PRs to specialized templates for bug fixes, features, and infrastructure changes. The goal is a system where developers fill in context naturally rather than treating the template as overhead.

Step-by-step guide

01

Create the default PR template file

In your repository root, create a directory called .github and add a file named PULL_REQUEST_TEMPLATE.md. This file's content will automatically populate the description field whenever someone opens a new pull request. GitHub looks for this file in .github/, docs/, or the repository root, but .github/ is the conventional location and keeps your root clean.

  • Create the .github directory if it does not exist
  • Add PULL_REQUEST_TEMPLATE.md with your template content
  • Commit and push to the default branch so it takes effect immediately
02

Design the template sections for maximum reviewer context

Structure the template with these sections: Summary (2-3 sentences on what and why), Changes Made (bulleted list of specific changes), How to Test (step-by-step manual test instructions or test commands), Screenshots (if UI changes), and Checklist (checkboxes for tests passing, documentation updated, migration included). Use Markdown headers and checkboxes so the template is scannable.

03

Add multiple templates for different change types

Create a .github/PULL_REQUEST_TEMPLATE/ directory and add separate files like feature.md, bugfix.md, infrastructure.md, and docs.md. When multiple templates exist, GitHub shows a template picker when opening a PR. Each template can have sections specific to that change type — bug fix templates include a Root Cause section, feature templates include a Product Spec Link section.

  • Create feature.md with sections for product context and feature flag details
  • Create bugfix.md with sections for root cause analysis and regression testing
  • Create infrastructure.md with sections for rollback plan and monitoring changes
04

Configure required sections with HTML comments

Use HTML comments inside the template to provide guidance that does not appear in the rendered PR. For example, place a comment under the Summary header that says what a good summary includes. Developers see this guidance while editing but reviewers see clean output. This technique teaches the format without cluttering the final PR description.

05

Integrate with branch protection and required checks

Go to Settings > Branches > Branch protection rules and enable Require a pull request before merging. While GitHub does not enforce template completion natively, you can add a CI check that parses the PR body for required sections and fails if they are empty. Tools like danger-js or a simple GitHub Action script can validate that the Summary and How to Test sections are filled in.

06

Add CODEOWNERS for automatic reviewer assignment

Create a .github/CODEOWNERS file that maps file paths to team members or GitHub teams. When a PR touches files matching a pattern, GitHub automatically requests reviews from the listed owners. This pairs well with PR templates because the right reviewers are assigned automatically, and the template gives them the context they need to review efficiently.

Common mistakes

Making the template too long and detailed

A template with 15 sections and 30 checkboxes trains developers to skip it entirely. Keep the default template to 5-6 sections that take under 2 minutes to fill in. If you need deeper context for specific change types, use multiple templates rather than one massive one.

Not putting the template on the default branch

GitHub loads the PR template from the base branch (usually main). If you only add the template to a feature branch, it will not appear when other developers open PRs against main. Always merge the template to your default branch first.

Using the template as a documentation substitute

PR templates capture the context for a specific change, not long-term documentation. If your template includes sections like Architecture Overview or Full API Documentation, that content belongs in your docs site or wiki, not in every PR description.

Forgetting to update templates as processes change

Templates go stale when team processes evolve. If you add a new CI check or change your deployment process, update the checklist in the template. Review templates quarterly and remove sections that developers consistently leave blank.

Tips

Add a link to your team's code review guidelines at the top of the template so new contributors can reference expectations without asking.

Use GitHub's query parameter feature to pre-fill labels — appending ?labels=bug to the new PR URL auto-applies the bug label alongside the bug fix template.

Include a checkbox for database migration included in the checklist section so reviewers know to check for migration files when relevant.

Keep a TEMPLATE_CHANGELOG.md in .github/ that documents when and why the template was updated so the team understands the rationale behind each section.

How Vantage helps

Vantage generates tickets with dependency context and acceptance criteria already attached, so when engineers open PRs for those tickets, the template can reference the Vantage ticket link for full product context. This eliminates the gap between what product specified and what engineering describes in the PR.

Frequently asked questions

Spend less time on setup, more on decisions

Vantage connects your tools and generates specs grounded in real data. Free to start.

Free to start. No credit card required.

Related reading