GitHub Pull Request Template: Examples, Setup Guide & Free Downloads

A GitHub pull request template is a markdown file that automatically populates the description field every time someone opens a new pull request. Instead of starting with a blank text box, the developer sees a structured form with the right prompts: what changed, why it changed, how to test it, and a pre-merge checklist. The result is faster reviews, fewer back-and-forth comments, and a git history that actually tells you what happened.

This guide covers everything specific to GitHub: how to create and place the template file, how to set up multiple templates, template variables and placeholders via GitHub Actions, organization-wide defaults, troubleshooting common issues, and ready-to-use examples you can copy-paste today.

Looking for templates that also work on GitLab and Bitbucket? Check out our general PR template guide with free downloads for all three platforms.

How to Add a Pull Request Template to Your GitHub Repository

GitHub looks for a specially named markdown file in your repository and uses its contents as the default PR description. You have three placement options:

• .github/pull_request_template.md (recommended)
• pull_request_template.md in the repo root
• docs/pull_request_template.md

The .github/ folder is the recommended location because it keeps repository configuration files organized in one place, alongside your workflows and issue templates.

Create the file, add your template content, commit it to your default branch, and every new PR will automatically use it:

mkdir -p .github
curl -o .github/pull_request_template.md \
  https://gitmore.io/blog/templates/pr-template-standard.md
git add .github/pull_request_template.md
git commit -m "Add PR template"
git push

What Makes a Great GitHub Pull Request Template

A bad template is just noise that developers will delete or ignore. A good template guides the developer to provide exactly the information a reviewer needs. Here are the essential sections every GitHub pull request template should include:

1. Description

A concise summary of what this PR does and why. Not a restatement of the ticket title, but actual context. A reviewer should understand the purpose of the change after reading this section alone.

2. Type of Change

A simple checkbox list: new feature, bug fix, refactor, docs, infra, performance. This takes 2 seconds to fill in and immediately tells the reviewer what kind of review is needed.

3. Changes Made

A bullet list of the specific changes. Not "updated files" but "Added rate limiting middleware to the /api/auth endpoint." Specificity saves review time.

4. How to Test

Step-by-step instructions for the reviewer to verify the change works. This is the most underused section in PR templates, and the most valuable.

5. Checklist

A pre-merge checklist the author completes before requesting review: tests passing, no console errors, documentation updated, self-review done.

6. Related Issues

Links to related tickets, issues, or other PRs. On GitHub, using "Closes #123" or "Fixes #456" will automatically close the linked issue when the PR is merged.

GitHub Pull Request Template Examples

Here are ready-to-use templates you can copy directly into your .github/pull_request_template.md file.

Standard Template

An all-purpose default that works for any type of change:

## Description

<!-- Provide a clear summary of what this PR does and why. -->

## Type of Change

- [ ] New feature
- [ ] Bug fix
- [ ] Refactoring (no functional changes)
- [ ] Documentation update
- [ ] Infrastructure / CI/CD
- [ ] Performance improvement

## Changes Made

<!-- List the specific changes. Be precise. -->

-
-
-

## How to Test

<!-- Step-by-step instructions for reviewers to verify this works. -->

1.
2.
3.

## Checklist

- [ ] Code follows the project's style guidelines
- [ ] Self-reviewed the code for obvious errors
- [ ] Added or updated tests where applicable
- [ ] Existing tests pass locally
- [ ] Updated documentation if needed
- [ ] No new warnings or console errors introduced

## Related Issues

<!-- Link related tickets or issues. Use "Closes #123" to auto-close. -->

## Screenshots

<!-- If applicable, add screenshots or screen recordings. -->

Feature Template

For new feature work that needs more context: user stories, architecture decisions, API changes, and feature flags:

## Feature Description

<!-- What does this feature do? Who is it for? Why is it needed? -->

## User Story

<!-- As a [type of user], I want [goal] so that [reason]. -->

## Implementation Details

<!-- Explain the technical approach and key decisions. -->

### Key Files Changed

| File | Change |
|------|--------|
|  |  |

## API Changes

| Method | Endpoint | Description |
|--------|----------|-------------|
|  |  |  |

## Database Changes

- [ ] No database changes
- [ ] Migration included and tested

## How to Test

1.
2.
3.

## Checklist

- [ ] Code follows the project's style guidelines
- [ ] Self-reviewed the code
- [ ] Added unit tests for new functionality
- [ ] Added integration tests where applicable
- [ ] Existing tests pass locally
- [ ] Updated documentation
- [ ] Backwards compatible (or migration plan documented)

## Feature Flag

- [ ] No feature flag needed
- [ ] Behind feature flag: `FLAG_NAME`

## Related Issues

## Screenshots / Demo

## Deployment Notes

<!-- Environment variables, dependencies, ordering? -->

Bug Fix Template

Bug fix PRs need a different structure. The reviewer needs to understand the original bug, the root cause, and why this specific fix is correct:

## Bug Description

<!-- What was the bug? Expected vs actual behavior. -->

**Expected:**

**Actual:**

## Root Cause

<!-- What caused this bug? Be specific. -->

## Fix Description

<!-- What does this PR change to fix the bug? -->

## How to Reproduce (Before Fix)

1.
2.
3.

## How to Verify (After Fix)

1.
2.
3.

## Impact Assessment

- **Severity:** Low / Medium / High / Critical
- **Users affected:** All / Subset (describe)
- **Duration:** Since when was this bug present?

## Regression Risk

<!-- Could this fix break anything else? -->

## Checklist

- [ ] Root cause identified and documented above
- [ ] Fix addresses the root cause (not just symptoms)
- [ ] Added test to prevent regression
- [ ] Existing tests pass locally
- [ ] Tested the specific reproduction steps

## Related Issues

<!-- Link the bug report. Use "Fixes #123" to auto-close. -->

Download All Templates

Grab the markdown files and drop them into your .github/ folder. Each template is ready to use or customize for your team.

How to Use Multiple Pull Request Templates on GitHub

A single template works for most teams, but larger organizations often need different templates for different types of work. GitHub supports multiple pull request templates through a folder-based approach.

Setting Up Multiple Templates

Instead of a single pull_request_template.md file, create a folder at .github/PULL_REQUEST_TEMPLATE/ and add separate markdown files for each template type:

.github/
└── PULL_REQUEST_TEMPLATE/
    ├── feature.md
    ├── bugfix.md
    ├── hotfix.md
    ├── refactor.md
    └── docs.md

Each file contains a different template tailored to that type of change. When a developer creates a new pull request, they select the template by appending a query parameter to the PR creation URL:

https://github.com/your-org/your-repo/compare/main...feature-branch?template=feature.md

GitHub Does Not Have a Native Template Dropdown

Unlike GitLab, which shows a dropdown menu to select a merge request template, GitHub does not provide a built-in template picker UI for pull requests. You must use the ?template=filename.md query parameter in the URL. There are a few practical ways to make this easier for your team:

• Browser bookmarks: Create bookmarks for each template URL (e.g., one for feature PRs, one for bug fixes).
• README links: Add links to your repository's README or CONTRIBUTING.md with pre-filled template URLs.
• CLI aliases: Use the GitHub CLI (gh pr create) with a --template flag to select templates from the command line.

GitHub Pull Request Template Variables and Placeholders

A common question is whether GitHub pull request templates support dynamic variables or placeholders like {{branch_name}}, {{author}}, or {{pr_number}}. The short answer: GitHub does not support native template variables. The template is treated as static markdown and inserted as-is into the PR description.

Workaround: GitHub Actions for Dynamic PR Descriptions

You can use a GitHub Actions workflow to automatically inject dynamic content into PR descriptions when a pull request is opened. This gives you the variable-like behavior that templates alone cannot provide:

# .github/workflows/pr-description.yml
name: Enrich PR Description

on:
  pull_request:
    types: [opened]

jobs:
  enrich:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - name: Add metadata to PR description
        uses: actions/github-script@v7
        with:
          script: |
            const pr = context.payload.pull_request;
            const currentBody = pr.body || '';
            const metadata = [
              '---',
              `**Branch:** ${pr.head.ref}`,
              `**Author:** @${pr.user.login}`,
              `**PR #:** ${pr.number}`,
              `**Base:** ${pr.base.ref}`,
              '---',
              ''
            ].join('\n');

            await github.rest.pulls.update({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: pr.number,
              body: metadata + currentBody
            });

This workflow runs automatically when a PR is opened and prepends the branch name, author, PR number, and base branch to the description. You can extend it to include Jira ticket links parsed from the branch name, deployment preview URLs, or any other dynamic data.

Using Placeholder Text in Templates

Since GitHub templates don't support dynamic variables natively, you can structure your template with clear placeholder text that developers replace manually:

## Description

<!-- Replace TICKET-NUMBER with your Jira/Linear ticket ID -->
**Ticket:** [TICKET-NUMBER](https://your-tracker.com/TICKET-NUMBER)

<!-- Replace with your actual description -->
[Describe what this PR does and why]

## PR Title Format

<!-- Use one of: feat: | fix: | refactor: | docs: | chore: -->
[type]: [short description]

Setting Up a Pull Request Template for Your GitHub Organization

If you manage multiple repositories across a GitHub organization, you don't want to copy the same template into every repo. GitHub supports organization-wide default templates through a special .github repository.

How the .github Repository Works

Create a repository named .github in your organization (e.g., your-org/.github). Any community health files you place in this repository become the defaults for all repositories in the organization that don't have their own versions.

# In your organization's .github repo:
your-org/.github/
├── pull_request_template.md          # Default PR template for all repos
├── PULL_REQUEST_TEMPLATE/
│   ├── feature.md                    # Org-wide feature template
│   └── bugfix.md                     # Org-wide bugfix template
├── ISSUE_TEMPLATE/
│   └── bug_report.md
└── CONTRIBUTING.md

Any repository that has its own pull_request_template.md will use its local version instead of the organization default. This gives you a sensible default across all repos while allowing individual teams to customize when needed.

Steps to Set Up Organization-Wide Templates

1. Go to your GitHub organization and create a new repository named .github (it must be public for open-source orgs, or can be private/internal for enterprise).
2. Add a pull_request_template.md file to the root of the repository.
3. Commit and push. Every repository in your organization that doesn't already have a PR template will now use this one by default.

Troubleshooting: Pull Request Template Not Working

If your GitHub pull request template isn't appearing when you create a new PR, work through this checklist:

1. Check the file path: The file must be named exactly pull_request_template.md (not pr_template.md or PR_TEMPLATE.md). Place it in one of these locations: .github/, the repo root, or docs/.
2. Check the branch: The template file must exist on the repository's default branch (usually main or master). A template on a feature branch won't be picked up.
3. Case sensitivity: The filename is case-insensitive on GitHub, but the folder name PULL_REQUEST_TEMPLATE/ for multiple templates must be uppercase.
4. File extension: Use .md as the extension. GitHub also supports .txt, but markdown is standard.
5. Conflicting files: If you have a pull_request_template.md in multiple locations (root, .github/, and docs/), GitHub uses the first one it finds in this priority order: .github/ > root > docs/.
6. Empty file: If the template file exists but is empty, GitHub will use it (resulting in a blank description). Make sure the file has actual content.
7. GitHub API / CLI: When creating PRs via the GitHub API or gh pr create, the template is not automatically applied unless you use the --template flag. Templates only auto-populate when creating PRs through the web UI.

GitHub Copilot and AI-Generated PR Descriptions

GitHub Copilot now offers an AI-powered "Generate PR description" button that analyzes your diff and writes a summary automatically. This is a useful complement to templates, not a replacement. Copilot fills in the what changed part, but templates ensure the why, how to test, and checklist sections are always present.

The best workflow combines both: use a pull request template for the structure, then let Copilot help fill in the description and changes sections. This gives you consistent formatting with AI-assisted content.

Better PR Descriptions, Better Reports

There's a compounding benefit to well-structured PR descriptions that most teams don't think about: they make every downstream tool more effective.

When your PRs have clear descriptions with type-of-change labels, your git history becomes a structured dataset. Automated reporting tools can then generate genuinely useful summaries because they have real context to work with. Instead of a report that says "5 PRs merged," you get a report that says "3 feature PRs shipped for the checkout redesign, 1 bug fix for the notification service, and 1 infrastructure update to the CI pipeline."

If you're using a git reporting tool to keep your team updated, structured PR descriptions are the single highest-leverage improvement you can make. The template gives the AI categorized, consistent input, and the output quality goes up dramatically.

Want to see what automated reports look like when your PRs are well-structured? Check out a demo report.

Frequently Asked Questions

How do I create a GitHub PR template?

Create a file named pull_request_template.md in your repository's .github/ directory. Add your template content in markdown format. GitHub will automatically use this file to populate the description field for every new pull request.

Why is my GitHub pull request template not working?

The most common causes are: the file is in the wrong location (it must be in the repo's default branch), the filename has a typo (it must be exactly pull_request_template.md), or the file is in a branch that isn't the default. Also check that the file isn't empty and uses valid markdown.

Can I use multiple GitHub PR templates?

Yes. Create a folder at .github/PULL_REQUEST_TEMPLATE/ with multiple markdown files (e.g., feature.md, bugfix.md). Users select a template by appending a query parameter to the PR creation URL, or you can use GitHub Actions to auto-apply templates based on branch naming conventions.

What should a GitHub PR template include?

At minimum: a description of what changed and why, type of change (feature, bug fix, refactor), testing instructions, and a pre-merge checklist. Optional but valuable: screenshots for UI changes, links to related issues, and deployment notes. See the templates above for ready-to-use examples.