Pull Request Checklist: Author & Reviewer Template (2026)
A pull request checklist is a short list of checks the author completes before asking for review, and the reviewer completes before approving. A good one covers scope and size, the description, tests and CI, security, and now AI-generated code. Copy the markdown below into .github/pull_request_template.md (or your GitLab or Bitbucket equivalent) and every new pull request starts with it.
2-minute setup • No credit card required
Copy-paste markdown
Drop one of these into your repository and every new request starts with the checklist. The full list with the reasoning behind each item is below.
GitHub
GitHub adds this file to the description of every new pull request in the repository. It also works at the repository root or in docs/. Azure DevOps reads the same content from .azuredevops/pull_request_template.md.
.github/pull_request_template.md## What does this PR do? <!-- One or two sentences. What changed, in plain words. --> ## Why? <!-- The problem or ticket this solves. Link it: Closes #123 --> ## How to test <!-- Steps a reviewer can follow to see it working. --> 1. 2. ## Screenshots / recording <!-- UI changes only. Before and after. Delete this section otherwise. --> ## Risk and rollback <!-- What could break, and how to undo it (revert, feature flag, migration down). --> ## Author checklist - [ ] The PR does one thing and is small enough to review in one sitting (aim for under 400 changed lines) - [ ] Branch is up to date with the target branch and has no merge conflicts - [ ] I reviewed my own diff: no debug logs, commented-out code, or unrelated changes - [ ] Tests cover the new behavior, and a regression test exists for any bug fix - [ ] CI passes (tests, lint, type check, build) - [ ] No secrets, tokens, or personal data in code, config, or logs - [ ] Database migrations are backward compatible with the currently deployed code - [ ] Docs, README, or API specs updated if behavior changed - [ ] AI-assisted code (if any) is disclosed, and I understand every line of it
GitLab
A file named Default.md in this folder is applied to every new merge request automatically. Other files in the folder appear in the Description template dropdown.
.gitlab/merge_request_templates/Default.md## What does this MR do? <!-- One or two sentences. What changed, in plain words. --> ## Why? <!-- The problem or ticket this solves. Link it: Closes #123 (or a Jira key) --> ## How to test <!-- Steps a reviewer can follow to see it working. --> 1. 2. ## Screenshots / recording <!-- UI changes only. Before and after. Delete this section otherwise. --> ## Risk and rollback <!-- What could break, and how to undo it (revert, feature flag, migration down). --> ## Author checklist - [ ] The MR does one thing and is small enough to review in one sitting (aim for under 400 changed lines) - [ ] Branch is up to date with the target branch and has no merge conflicts - [ ] I reviewed my own diff: no debug logs, commented-out code, or unrelated changes - [ ] Tests cover the new behavior, and a regression test exists for any bug fix - [ ] CI passes (tests, lint, type check, build) - [ ] No secrets, tokens, or personal data in code, config, or logs - [ ] Database migrations are backward compatible with the currently deployed code - [ ] Docs, README, or API specs updated if behavior changed - [ ] AI-assisted code (if any) is disclosed, and I understand every line of it
Bitbucket
Bitbucket Cloud doesn't read template files from the repository. Paste this shorter version into the repository's default description setting instead. For items that must block the merge, add them as pull request tasks and turn on the merge check for incomplete tasks.
Repository settings → Pull requests → Default description## What does this PR do? ## Why? (ticket) ## How to test 1. 2. ## Risk and rollback ## Author checklist - [ ] Does one thing, under ~400 changed lines - [ ] Up to date with the target branch - [ ] Self-reviewed: no debug code or unrelated changes - [ ] Tests added or updated; Pipelines green - [ ] No secrets or personal data - [ ] Migrations backward compatible - [ ] Docs updated if behavior changed - [ ] AI-assisted code disclosed and understood
Reviewer
For the person approving. Save it as a saved reply (GitHub) or comment template (GitLab), or keep it in your CONTRIBUTING.md so reviewers check the same things every time.
pr-review-checklist.md### Review checklist - [ ] I understand why this change exists (ticket, description, or a question asked) - [ ] The code does what the description says, including errors, empty states, and edge cases - [ ] The design fits the codebase: no needless abstraction, no duplicated logic - [ ] Names and structure are clear enough to change safely in six months - [ ] Tests check behavior, would fail if the logic broke, and are not flaky - [ ] Input is validated, permissions are checked, and nothing sensitive is logged - [ ] No obvious performance trap (N+1 queries, unbounded loops, missing pagination) - [ ] AI-generated parts call real APIs and packages that exist, at the right versions - [ ] Comments are marked as blocking or nit, and each blocking one says what would resolve it
Before You Open the Pull Request
Most review delays start here. A PR that is small, current, and self-reviewed gets reviewed faster and comes back with fewer comments.
Title and Description
The description is for two readers: the reviewer today, and whoever runs git blame on this code next year.
Tests and CI
Anything a machine can check should be checked by CI, not by a human reading the diff.
Security, Data, and Performance
These are the problems that are cheap to catch in review and expensive to catch in production.
AI-Generated Code
Code from Copilot, Cursor, Claude Code, or Codex gets the same review as human code, plus a few checks that matter more for generated code.
Reviewer Checklist
What the person approving should check. Read the description first, then the tests, then the code.
Merging and After
The PR isn't done when it's approved. It's done when the change works in production.
Expert advice
- 1
Keep the checklist in the template to 8 to 10 items. A 30-item checklist gets ticked without being read. The full list on this page is for agreeing on standards; the template is the short version people actually use.
- 2
Remove any item CI can check. "Code is formatted" and "tests pass" belong in required status checks, not in a box someone ticks. Human checklists should cover what machines can't judge: why, risk, design, and test quality.
- 3
Use different templates for different PR types. GitHub supports several files in .github/PULL_REQUEST_TEMPLATE/ (picked with ?template=name.md in the URL) and GitLab shows every file in .gitlab/merge_request_templates/ in a dropdown. A hotfix needs a rollback plan; a docs change needs almost nothing.
- 4
A ticked box in a description doesn't block anything by itself. If an item truly must happen, enforce it: required status checks and conversation resolution on GitHub, merge checks on GitLab, incomplete-task merge checks on Bitbucket.
- 5
Review the checklist every quarter. If an item never catches anything, delete it. If the same problem keeps reaching production, add a check for it. Track PR size and review time so you can see whether the changes help.
Common questions
What should a pull request checklist include?
For the author: one logical change under about 400 lines, a self-reviewed diff, a description that explains why, a linked ticket, steps to test, tests for new behavior, green CI, no secrets, and backward compatible migrations. For the reviewer: correctness and edge cases, design fit, readability, test quality, security, and clearly labeled comments. In 2026, add a line for AI-generated code: disclosed, understood, and checked for invented APIs.
How do I add a checklist to every pull request automatically?
Put the checklist in a template file. On GitHub, save it as .github/pull_request_template.md. On GitLab, save it as .gitlab/merge_request_templates/Default.md. On Azure DevOps, use .azuredevops/pull_request_template.md. Bitbucket Cloud doesn't read template files, so paste it into Repository settings, Pull requests, Default description. New pull requests then start with the checklist in the description.
What is the difference between a pull request template and a pull request checklist?
A pull request template is the file that pre-fills the description of every new pull request. A checklist is one part of it: the list of - [ ] items the author ticks before requesting review. Most templates also include sections for what changed, why, how to test, and screenshots. See our pull request template guide for full template examples.
How big should a pull request be?
Aim for under 400 changed lines, and smaller is better. The SmartBear and Cisco study of code review found reviewers catch the most defects when reviewing 200 to 400 lines at a time. Google's engineering practices call about 100 lines reasonable and 1,000 lines usually too large. Split larger work into stacked pull requests or ship it behind a feature flag.
Can a pull request checklist block merging?
Not on its own. Unticked boxes in a description don't stop the merge button on GitHub, GitLab, or Bitbucket. To enforce a rule, use the platform's controls: required status checks and conversation resolution in GitHub branch protection, merge checks and approval rules in GitLab, and the incomplete-tasks merge check in Bitbucket. Some teams add a CI job that fails while any required box is unticked.
Should reviewers have their own checklist?
Yes. The author checklist is about readiness; the reviewer checklist is about judgment: is it correct, does the design fit, would the tests catch a real bug, is it safe. Keep it in CONTRIBUTING.md or as a saved reply so every reviewer checks the same things. It also makes reviews from new team members much more consistent.
How should a checklist handle AI-generated code?
Add three checks: the author discloses which parts were generated (in the description or with a Co-authored-by trailer), the author understands every line, and someone confirms that the APIs, options, and packages the code uses actually exist at the versions in the project. Generated PRs also tend to be large, so the size limit matters more.
How fast should a pull request be reviewed?
Within one business day at most. That's the limit Google's engineering practices recommend for responding to a review request. Faster first responses keep authors from batching work into larger pull requests, which take longer to review. Tracking time to first review each week is the easiest way to see if your team is keeping up.
Keep reading
Templates and checklists that go with this one.
Pull Request Template Guide: Examples & Free Downloads
Full PR templates (feature, bugfix, hotfix, release) with the sections beyond the checklist.
Read moreGitHub Pull Request Template: Setup Guide
Where .github/pull_request_template.md goes, multiple templates, and org-wide defaults.
Read moreGitLab Merge Request Template: Examples & Setup
Default.md, template priority, quick actions, and five downloadable MR templates.
Read moreCode Review Process Checklist
The team-level side: reviewer assignment, review SLAs, feedback quality, and automation.
Read moreAutomate Your Git Reporting
Stop compiling reports manually. Let your code speak for itself with automated daily and weekly reports.
Get Started FreeNo credit card • No sales call • Reports in 2 minutes