GitHub pull request template: setup and 4 examples

A GitHub pull request template is a Markdown file, usually saved as .github/pull_request_template.md, whose contents GitHub puts in the description of every new pull request in the repository. Merge it into the default branch, and contributors start from your headings and checklist instead of an empty box.

If you're new to the workflow, start with what a pull request is and how it moves from branch to merge.

How GitHub pull request templates work

GitHub looks for the template on the repository's default branch, in one of three places (GitHub Docs):

Pick one. If a repository has the file in more than one place, GitHub's order of precedence for community health files is the .github folder, then the root, then docs (GitHub Docs).

Three rules trip people up (About issue and pull request templates):

• It only works from the default branch. Templates created on other branches aren't available to collaborators, so a template sitting in an open pull request does nothing until that pull request merges.

• The file name isn't case sensitive. PULL_REQUEST_TEMPLATE.md works as well as pull_request_template.md, and the extension can be .md or .txt.

• It pre-fills, it doesn't enforce. The template's contents appear in the pull request body, and the author edits them like any description. Issue templates can be forms with required fields; pull request templates are plain Markdown or text files.

Add a template in the GitHub UI

1. On the repository's main page, open the Add file menu and click Create new file.

2. Name the file .github/pull_request_template.md.

3. Paste one of the templates below.

4. Click Commit changes. If your current branch is the default branch, GitHub's docs suggest committing to a new branch and opening a pull request.

5. Merge that pull request. New pull requests get the template from then on.

Or from the command line

git switch -c add-pr-template
mkdir -p .github
# Write your template to .github/pull_request_template.md, then:
git add .github/pull_request_template.md
git commit -m "Add pull request template"
git push -u

git switch -c add-pr-template
mkdir -p .github
# Write your template to .github/pull_request_template.md, then:
git add .github/pull_request_template.md
git commit -m "Add pull request template"
git push -u

git switch -c add-pr-template
mkdir -p .github
# Write your template to .github/pull_request_template.md, then:
git add .github/pull_request_template.md
git commit -m "Add pull request template"
git push -u

Open a pull request for the branch and merge it.

Multiple pull request templates and the template parameter

For different kinds of change, put several templates in a PULL_REQUEST_TEMPLATE folder inside the root, docs/ or .github/:

To use one, add template to a compare URL. quick_pull=1 opens the "Open a pull request" page for the two branches (GitHub Docs):

The same URL can pre-fill title, body, labels, milestone, assignees and projects. Each of those needs the matching permission: someone who can't add labels gets a 404 Not Found from a link that sets labels. Leave them out of links meant for outside contributors.

GitHub's docs describe this parameter as the way to choose a template from the folder; they don't describe a template picker on the pull request page. Put the links where contributors will see them, such as CONTRIBUTING.md. If you also keep a single default file next to the folder, open a test pull request after merging to check which template appears without the parameter.

From the terminal, the GitHub CLI can start a pull request from a template file: gh pr create --template "pull_request_template.md" uses it as the starting body text (GitHub CLI manual).

Organization-wide default templates

To give every repository in an organization or personal account the same template, create a public repository named .github and add the template to its root, .github/ folder or docs/ folder. GitHub then uses it for any repository owned by that account that doesn't have its own template, whatever that repository's visibility. A repository with its own template keeps it, and the .github repository can't be private (GitHub Docs).

What to put in a pull request template

A useful template asks for what the reviewer can't get from the diff and stays short enough that people fill it in. A few habits help:

• Ask for the why. The diff shows what changed. The reviewer needs the reason, the linked issue and what could break.

• Hide instructions in HTML comments. GitHub hides <!-- ... --> from the rendered description, so prompts guide the author without cluttering the page (GitHub Docs).

• Link issues with a closing keyword. Closes #123, Fixes #123 or Resolves #123 in the description closes the issue when the pull request merges, but only when the pull request targets the default branch (GitHub Docs).

• Use task lists for checks. - [ ] makes a checkbox and - [x] a checked one (GitHub Docs). Keep the list to checks people run.

• Don't expect it to fix big diffs. A summary section helps, but it can't make a huge pull request easy to review.

The template is the author's half of review. The reviewer's half is a code review checklist, and how to review a pull request on GitHub walks through the review itself.

Why the templates have an optional AI field

The author is the only person who knows which parts a coding agent wrote. One optional field records it: whether an agent wrote part of the change, and which parts. That tells a reviewer where to read closely. Authors who wrote it all themselves can delete the field.

AI-written code still ships bugs. Bug Bench, cubic's public benchmark, counts review findings on AI-written code that a developer upvoted or a coding agent addressed. Across the seven ranked models, relative bug rates run from 0.65 to 1.50, where 1.00 is the average across all AI-attributed lines and lower is better. The data is observational: teams choose their models, so a rate reflects the code each model was used for as well as the model.

Automated checks belong in the testing section: tests, CI, linters, or AI code review from a tool such as cubic, which reviews pull requests on GitHub, finds bugs and learns a team's rules. If a coding agent opens pull requests for you, tell it in its instructions file (AGENTS.md or CLAUDE.md) to fill in your template, AI field included.

Four pull request templates you can copy

Save the default as .github/pull_request_template.md and the others in .github/PULL_REQUEST_TEMPLATE/. Each block is a whole file. Delete any section your team doesn't use.

1. General default template

## What and why
<!-- What does this change do, and why is it needed? -->

Closes #

## How to test
<!-- Steps a reviewer can follow, or the tests that cover this change. -->

## Risk
<!-- What could break? Migrations, config, feature flags, anything to watch after deploy. -->

## AI assistance (optional)
<!-- Did a coding agent write part of this change? If so, which parts? -->

## What and why
<!-- What does this change do, and why is it needed? -->

Closes #

## How to test
<!-- Steps a reviewer can follow, or the tests that cover this change. -->

## Risk
<!-- What could break? Migrations, config, feature flags, anything to watch after deploy. -->

## AI assistance (optional)
<!-- Did a coding agent write part of this change? If so, which parts? -->

## What and why
<!-- What does this change do, and why is it needed? -->

Closes #

## How to test
<!-- Steps a reviewer can follow, or the tests that cover this change. -->

## Risk
<!-- What could break? Migrations, config, feature flags, anything to watch after deploy. -->

## AI assistance (optional)
<!-- Did a coding agent write part of this change? If so, which parts? -->

2. Bug fix template

Save as .github/PULL_REQUEST_TEMPLATE/bug_fix.md and link to it with ?quick_pull=1&template=bug_fix.md.

## Bug
<!-- What did users see? Link the issue below. -->

Fixes #

## Root cause
<!-- Why it happened. Point to the commit or line that introduced it, if known. -->

## Fix
<!-- What this change does about the root cause, not only the symptom. -->

## Proof
- [ ] A test fails without this fix and passes with it
- [ ] I reproduced the bug before the fix and confirmed it is gone after

## Same bug elsewhere
<!-- Does the same pattern exist in other places? Fixed here, tracked in an issue, or not affected? -->

## AI assistance (optional)
<!-- Did a coding agent write part of this fix? If so, which parts? -->

## Bug
<!-- What did users see? Link the issue below. -->

Fixes #

## Root cause
<!-- Why it happened. Point to the commit or line that introduced it, if known. -->

## Fix
<!-- What this change does about the root cause, not only the symptom. -->

## Proof
- [ ] A test fails without this fix and passes with it
- [ ] I reproduced the bug before the fix and confirmed it is gone after

## Same bug elsewhere
<!-- Does the same pattern exist in other places? Fixed here, tracked in an issue, or not affected? -->

## AI assistance (optional)
<!-- Did a coding agent write part of this fix? If so, which parts? -->

## Bug
<!-- What did users see? Link the issue below. -->

Fixes #

## Root cause
<!-- Why it happened. Point to the commit or line that introduced it, if known. -->

## Fix
<!-- What this change does about the root cause, not only the symptom. -->

## Proof
- [ ] A test fails without this fix and passes with it
- [ ] I reproduced the bug before the fix and confirmed it is gone after

## Same bug elsewhere
<!-- Does the same pattern exist in other places? Fixed here, tracked in an issue, or not affected? -->

## AI assistance (optional)
<!-- Did a coding agent write part of this fix? If so, which parts? -->

3. Feature template

Save as .github/PULL_REQUEST_TEMPLATE/feature.md.

## Summary
<!-- What this adds and who it's for. Link the issue, spec or design doc. -->

Closes #

## Changes
<!-- The main parts, in the order a reviewer should read them. -->
-

## Out of scope
<!-- What this pull request leaves for later. -->

## How to test
<!-- Steps, test accounts, feature flags to turn on. -->

## Rollout
- [ ] Behind a feature flag, or safe to ship on merge
- [ ] Migrations are backward compatible
- [ ] Logs, metrics or alerts cover the new path

## AI assistance (optional)
<!-- Did a coding agent write part of this change? If so, which parts? -->

## Screenshots
<!-- For UI changes: before and after. -->

## Summary
<!-- What this adds and who it's for. Link the issue, spec or design doc. -->

Closes #

## Changes
<!-- The main parts, in the order a reviewer should read them. -->
-

## Out of scope
<!-- What this pull request leaves for later. -->

## How to test
<!-- Steps, test accounts, feature flags to turn on. -->

## Rollout
- [ ] Behind a feature flag, or safe to ship on merge
- [ ] Migrations are backward compatible
- [ ] Logs, metrics or alerts cover the new path

## AI assistance (optional)
<!-- Did a coding agent write part of this change? If so, which parts? -->

## Screenshots
<!-- For UI changes: before and after. -->

## Summary
<!-- What this adds and who it's for. Link the issue, spec or design doc. -->

Closes #

## Changes
<!-- The main parts, in the order a reviewer should read them. -->
-

## Out of scope
<!-- What this pull request leaves for later. -->

## How to test
<!-- Steps, test accounts, feature flags to turn on. -->

## Rollout
- [ ] Behind a feature flag, or safe to ship on merge
- [ ] Migrations are backward compatible
- [ ] Logs, metrics or alerts cover the new path

## AI assistance (optional)
<!-- Did a coding agent write part of this change? If so, which parts? -->

## Screenshots
<!-- For UI changes: before and after. -->

4. Short template for small teams

For a small team that reviews each other's work every day, five lines may be enough:

GitLab merge request templates

GitLab calls pull requests merge requests, and its templates work a little differently (GitLab Docs):

• Save each template as a .md file in .gitlab/merge_request_templates/ on the default branch.

• Authors pick a template from the Choose a template dropdown when they create or edit a merge request.

• A template named Default.md (case-insensitive) pre-fills every new merge request. On Premium and Ultimate you can set a default in Settings > Merge requests instead, and that setting takes priority over Default.md.

• The default template can use variables such as %{source_branch}, %{target_branch} and %{all_commits}, which GitLab fills in when the merge request is first saved.

• Project templates work on Free, Premium and Ultimate. Group-level and instance-level templates, which projects inherit, need Premium or Ultimate.

For how the two review flows differ beyond templates, see pull request vs merge request.

Pair the template with review rules

A template asks the author for context. Two other settings decide who reads it and when the pull request can merge: a CODEOWNERS file requests reviews from the owners of the paths a pull request changes, and a branch protection rule or ruleset can require their approval. For more ways to shorten the wait between opening and merging, see how to speed up PR reviews on GitHub.

Treat the template like code. If authors delete the same section every time, cut it in a pull request of its own.

FAQ

What is a pull request template?

A pull request template is a Markdown or text file in your repository that GitHub uses to pre-fill the description of new pull requests. It usually asks for a summary, a linked issue, testing notes and a short checklist. GitHub only uses it once it's on the default branch.

What is a good pull request template?

A good template is short and asks only for what a reviewer can't see in the diff: why the change exists, how it was tested, what could break and, optionally, which parts a coding agent wrote. Put instructions in HTML comments so they don't show in the rendered description. If authors delete a section every time, cut it.

How do I add a pull request template in GitHub?

Create a file named pull_request_template.md in .github/, the repository root or docs/, write the template in Markdown, and merge it into the default branch. New pull requests then open with its contents in the description. A template on any other branch isn't used.

How do I use a specific pull request template?

Put your templates in a PULL_REQUEST_TEMPLATE folder, then open the pull request from a compare URL ending in ?quick_pull=1&template=<file name>, such as .../compare/main...my-branch?quick_pull=1&template=bug_fix.md. From the terminal, gh pr create --template <file> starts the description from a template file.

How do I format a pull request description?

GitHub formats pull request descriptions with GitHub Flavored Markdown, so headings, lists, task lists, fenced code blocks, @mentions and links to issues all work, and the description box has a formatting toolbar for the common ones. Start with a short summary of what the change does, then why it's needed and how to test it. A template gives every new pull request that structure without anyone retyping it.