Skip to main content
Checklist • 34 items

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
0 of 34 completed
0%

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.

Pro Tips

Expert advice

  1. 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. 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. 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. 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. 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.

FAQ

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.

Automate Your Git Reporting

Stop compiling reports manually. Let your code speak for itself with automated daily and weekly reports.

Get Started Free

No credit card • No sales call • Reports in 2 minutes