GitHub pull request template: examples you can copy

How to add a pull request template on GitHub

1. Create a branch. Create a branch from your default branch for the template commit.
2. Add the template file. Add a file named pull_request_template.md to the .github folder, the repository root or the docs folder.
3. Write the sections. Write the headings and prompts you want in every pull request description, in Markdown.
4. Merge it into the default branch. Open a pull request and merge it. Templates are available to collaborators once they are on the default branch.
5. Open a pull request to check it. Open a new pull request. The template fills the description box automatically.

The template only seeds the description box, and the author can edit or delete any of it. That makes a template a prompt rather than a gate: what must hold on every merge belongs in CI or a required check.

mkdir -p .github
touch .github/pull_request_template.md
git checkout -b add-pr-template
git add .github/pull_request_template.md
git commit -m "Add pull request template"
git push -u origin add-pr-template

Where the template file can live

GitHub reads a single pull request template from three places. File names aren’t case sensitive and can end in .md or .txt.

Keep one copy. For community health files that can live in several places, GitHub’s docs give the order .github, then the root, then docs, so a stray second file quietly loses.

How to use multiple pull request templates

A repository with different kinds of change, such as bug fixes, features and releases, can keep one template for each in a PULL_REQUEST_TEMPLATE subdirectory of .github, the root or docs:

.github/
  pull_request_template.md
  PULL_REQUEST_TEMPLATE/
    bug_fix.md
    feature.md
    release.md

You choose one with the template query parameter on the compare URL, together with quick_pull=1, which opens the “Open a pull request” page for the two branches:

https://github.com/OWNER/REPO/compare/main...my-branch?quick_pull=1&template=bug_fix.md

The same URL accepts title, body, labels, milestone, assignees and projects, so a team can bookmark a link that opens a release pull request with the right template and label. Link those URLs from your CONTRIBUTING.md so people find them. From the terminal, gh pr create --template bug_fix.md starts the body from a template file.

A pull request template on GitHub is a Markdown file that pre-fills every new pull request description. One file named pull_request_template.md in .github/, the root or docs/ is the default. Several templates go in a PULL_REQUEST_TEMPLATE/ folder, picked with ?template= on the compare URL. All must be on the default branch.

How to set a default template for an organization

To give every repository the same template, create a public repository named .github in your organization or personal account and add pull_request_template.md to its root, its .github folder or its docs folder. GitHub uses that default in any repository the account owns that has no template of its own, private repositories included. The .github repository itself has to be public.

A repository that adds its own template overrides the default. That lets a platform team set a baseline and a service with special needs, such as a database migration checklist, keep its own.

What to put in a pull request template

A good template asks for what the diff can’t show. The code tells a reviewer what changed; only the author knows why, what they ruled out and how they checked it. Aim for four to six sections:

• Summary: what the change does and why, in two or three sentences.
• Linked issue: a closing keyword such as Fixes #123, which closes the issue when the pull request merges into the default branch.
• How it was tested: the commands run, the cases checked by hand, and screenshots for UI changes.
• Risk and rollback: what could break, who is affected and how to undo it.
• Where to look: the files or decisions that deserve the reviewer’s attention first.
• A short checklist: only for things people actually forget, such as migrations, docs or feature flags.

Put instructions in HTML comments. GitHub hides <!-- … --> content from the rendered description, so the prompts guide the author without cluttering the page when nobody deletes them. Checkboxes use the task-list syntax - [ ], and - [x] marks one done.

Pull request template examples you can copy

General template

A default that fits most changes. Save it as .github/pull_request_template.md.

## Summary
<!-- What does this change do, and why? Two or three sentences. -->

Fixes #

## How it was tested
<!-- Commands you ran, cases you checked by hand, screenshots for UI. -->

## Risk and rollback
<!-- What could break, who is affected, and how to undo it. -->

## Where to look
<!-- The file or decision you most want a second opinion on. -->

## Checklist
- [ ] Tests added or updated
- [ ] Docs updated, or not needed
- [ ] No secrets, tokens or personal data in code or logs

Bug fix template

A fix is easiest to review when the reviewer can see the cause, not only the symptom. Save it as .github/PULL_REQUEST_TEMPLATE/bug_fix.md.

## Bug
Fixes #
<!-- What the user saw, and the input or state that triggers it. -->

## Root cause
<!-- Why it happened. Link the line or commit that introduced it. -->

## Fix
<!-- What changed, and why this is the right place to fix it. -->

## Verification
- [ ] A test that failed before this change and passes now
- [ ] Checked nearby code for the same mistake

## Risk
<!-- Other callers of the changed code, and anything that relied on the old behavior. -->

Feature template

Features need the context a reviewer can’t get from code: the product decision and what was left out. Save it as .github/PULL_REQUEST_TEMPLATE/feature.md.

## What and why
<!-- The user-facing change and the problem it solves. Link the spec or issue. -->

Closes #

## Scope
<!-- What this PR includes, and what is deliberately left for later. -->

## Design decisions
<!-- Options you considered and why you chose this one. -->

## Screenshots or recordings
<!-- Before and after, for any UI change. -->

## Rollout
- [ ] Behind a feature flag, or safe to ship to everyone
- [ ] Database migration is backward compatible
- [ ] Analytics or logging added where needed

## How it was tested
<!-- Automated tests, plus the manual path you followed. -->

Template for pull requests written by a coding agent

Coding agents such as Codex, Claude Code and Copilot can open pull requests on their own. Their descriptions can end up restating the diff. A template that asks for the task, the assumptions and the evidence gives the human reviewer something the diff doesn’t. Point your agent at it from AGENTS.md, for example: “When you open a pull request, fill in .github/PULL_REQUEST_TEMPLATE/agent.md.”

## Task
<!-- The request or issue the agent worked from, quoted or linked. -->

Fixes #

## What the agent changed
<!-- A short summary in plain language, not a file-by-file list. -->

## Assumptions
<!-- Anything the agent decided that the task didn't specify. -->

## Evidence
<!-- Commands run and their results: tests, type check, lint, build. -->

## Not done
<!-- Parts of the task skipped or left for a human, and why. -->

## Human review
- [ ] A person has read the full diff
- [ ] New dependencies, permissions and network calls are expected
- [ ] Tests exercise the new behavior, not only the happy path

The Assumptions and Not done sections matter most. They surface the gaps a confident description can hide. For more on reviewing this kind of change, see reviewing AI-generated code.

Pull request template best practices

• Keep it short. A template people fill in beats a thorough one they delete. Start with the general template and add a section only when reviews keep asking the same question.
• Ask questions, not for ceremony. “How did you test this?” gets a real answer; a checkbox that says “I have tested my code” gets ticked.
• Use checkboxes for steps people forget. Migrations, docs and feature flags are good candidates. Style rules aren’t: a linter checks them every time.
• Link issues with closing keywords. close, fixes, resolves and their variants link the issue and close it on merge, but only when the pull request targets the default branch. For another repository, write Fixes octo-org/octo-repo#100.
• Review the template like code. It lives in the repository, so changes go through a pull request and the team agrees on them.

How the template helps code review, human and AI

The description is the first thing a reviewer reads, and AI reviewers read it too. HeyDeer reviews each pull request in the context of the whole repository and also reads the PR title, description and discussion, plus related issues in the same repository, such as the one a Fixes # line links. A clear summary, the reason for the change and what was deliberately left out help any reviewer tell an intended behavior change from a bug.

A pull request template and a review guide do different jobs. The template holds the author’s context for one change: why it exists, how it was tested, what to look at. Review rules hold what every review should check in the codebase, so they belong in a file such as REVIEW.md, which HeyDeer and Claude Code Review both read.

Coding conventions, the ones both people and agents should follow when they write code, fit best in an AGENTS.md file. Requirements that must hold in every matching pull request, such as access checks on API routes, can be a repository check that HeyDeer verifies on its own. See how HeyDeer applies review rules for how the pieces fit together.

Sources

1. GitHub Docs: Creating a pull request template for your repository
2. GitHub Docs: About issue and pull request templates
3. GitHub Docs: Using query parameters to create a pull request
4. GitHub Docs: Creating a default community health file
5. GitHub Docs: Linking a pull request to an issue
6. GitHub Docs: Basic writing and formatting syntax
7. GitHub CLI manual: gh pr create