QUICK ANSWER
What should a pull request template include?
A pull request template should prompt the author for the change purpose, linked work, bounded scope, evidence, tests and limitations, risks, migration, rollback, documentation, dependencies, and reviewer guidance. It should not claim that code review, CI, approval, merge authorization, security assessment, deployment, rollback execution, or production verification is complete.
A useful pull request template helps an author explain why a change exists, what is and is not changing, which evidence supports it, how it was tested, and where reviewers should focus. It prepares a proposal for review without pretending that the review, approval, merge, deployment, or production verification has happened.
This original pack includes editable Markdown, a fictional completed description, a machine-readable record, a closed JSON Schema, a dependency-free validator, 62 tests, and a deterministic ZIP builder. The fields are provider-neutral, while installation paths and platform behavior remain specific to GitHub, GitLab, or another repository host.
Write the proposal reviewers need before review starts
Keep the author-owned description concise, evidence-linked, and explicit about uncertainty. Put repository-wide guidance and reviewer decisions on their own accountable surfaces.
Define the change and its boundary
State the observable problem, proposed approach, expected impact, included paths, exclusions, non-goals, and related work. The template should explain the proposal, while the repository README explains the project and CONTRIBUTING.md explains the standing contribution workflow.
Sources: [pull-request-pack], [github-pull-request-template], [github-readme], [github-contributing]
Attach evidence without overstating it
Give screenshots, reproductions, test results, metrics, and design decisions stable references, owners, dates, findings, and limitations. An author-reported passed test remains bounded evidence; configured CI and repository rules remain authoritative for enforced checks.
Sources: [pull-request-pack]
Expose risk, migration, rollback, and dependencies
Name credible failure scenarios, mitigations, owners, migration-plan references, rollback triggers, reversible steps, documentation decisions, and unresolved dependencies. Describing these records does not authorize any migration, deployment, or rollback action.
Sources: [pull-request-pack]
Install the template in the provider-specific location
For one GitHub template, copy the Markdown to .github/pull_request_template.md, the repository root, or docs. GitHub supports multiple templates under PULL_REQUEST_TEMPLATE directories. GitLab merge request templates use .gitlab/merge_request_templates and must be present on the default branch.
Sources: [github-pull-request-template], [gitlab-description-templates]
Validate the record, then hand it to reviewers
Run the packaged validator and tests, replace every fictional value, verify links and commands, and request the appropriate reviewers through the repository workflow. A code review checklist then owns inspection of the diff, findings, and follow-up; this PR description does not complete that work.
Sources: [pull-request-pack], [github-contributing]
The pull request template owner boundary
This page owns the author-supplied description of one proposed change. It links adjacent records without absorbing their jobs or authority.
Included
- Change purpose, linked work, repository references, included and excluded scope, evidence, tests, limitations, risks, migration, rollback, documentation, dependencies, and reviewer navigation
- Editable Markdown, fictional Markdown and JSON examples, provider-neutral policy, closed Draft 2020-12 schema, dependency-free validator, mutation tests, and deterministic ZIP
- Current GitHub and GitLab placement guidance with an explicit default-branch requirement
Not included
- Reviewer inspection criteria, code-review findings, approvals, requested changes, or follow-up ownership, which belong to the code review checklist and repository review process
- Project overview, installation, usage, support, and project maintenance, which belong to the repository README, or standing contribution rules, which belong to CONTRIBUTING.md
- CI configuration, branch protection, rulesets, required reviewers, merge queues, merge action, release authorization, deployment, rollback execution, or production verification
- Any claim that a completed description proves the change correct, secure, accessible, compliant, approved, merged, deployed, or production-ready
DOWNLOADABLE RESOURCE
Download the pull request template pack
Start with the editable Markdown, inspect the fictional example and policy, then use the JSON record, schema, validator, and tests when you need machine-checkable consistency.
Pull request template pack
An original author-context pack for scope, evidence, tests, risks, migration, rollback, documentation, dependencies, and reviewer guidance.
Format: Editable Markdown, fictional Markdown and JSON, policy, JSON Schema, validator, tests, and deterministic builder in one ZIP
Locally reproduced August 1, 2026. SHA-256: c5e407db9893ea7ea82aa88c6fadd07146a32c3970d01ca560d4d48332c41743
Included
- Editable pull request description and a clearly fictional completed Markdown example
- Machine-readable fictional change record plus provider-neutral section and evidence policy
- Closed JSON Schema Draft 2020-12 contract and dependency-free validator
- 62 positive, mutation, cross-reference, boundary, command, URL, and secret-safety tests
- Exact-ten-file deterministic ZIP builder with clean extraction and source-byte parity checks
Verification boundary
Validated the fictional record and policy, ran 62 packaged tests, checked the exact ten-file allowlist and top-level clean extraction, compared every archived file with its source, and reproduced identical bytes under UTC and Pacific/Auckland time zones.
Three ways to adapt the author-context record
Keep the same authority boundary while changing field depth and installation to fit the repository host and actual risk.
Provider-neutral bounded change record
Use when: A team wants one stable description model that can be copied into different repository platforms or internal tooling.
Use stable IDs for work, evidence, tests, risks, migration, rollback, documentation, dependencies, and reviewer guidance while keeping every authority flag false.
Structure
- Author-owned context and evidence linked through a closed record graph
- Explicit false boundaries for review, CI, approval, merge, deployment, and production claims
Watch for: Provider-neutral fields do not make installation behavior portable; confirm the exact path and inheritance rules for the target host.
Sources: [pull-request-pack], [github-contributing]
GitHub pull request template
Use when: Contributors open pull requests on GitHub and should see one default prompt or choose among multiple prompts.
Use .github/pull_request_template.md for one hidden default template, or a supported PULL_REQUEST_TEMPLATE directory and template query parameter for multiple templates.
Structure
- Commit the selected Markdown file to the default branch
- Keep project-wide contribution rules in CONTRIBUTING.md and reviewer decisions in the review process
Watch for: A visible template can request context, issue references, and reviewer mentions, but it does not configure owners, checks, rulesets, or approval requirements.
Sources: [github-pull-request-template], [github-readme], [github-contributing]
GitLab merge request template
Use when: Contributors open merge requests on GitLab and need a selectable or default description template.
Copy the adapted Markdown into .gitlab/merge_request_templates with an .md extension on the default branch, then verify its appearance in the template selector.
Structure
- Choose a repository, group, or instance template level deliberately
- Review current inheritance and default-template priority before rollout
Watch for: GitLab supports variables, quick actions, inheritance, and plan-dependent settings that this provider-neutral pack does not configure or test.
Sources: [gitlab-description-templates], [pull-request-pack]
Decide whether the description is ready for review
A useful author record makes the change inspectable and unresolved work visible. It does not grant a reviewer or repository decision.
The purpose, scope, or expected impact cannot be stated without vague language.
Choose: Return to the related work and implementation boundary before requesting review.
Tradeoff: Review starts later, but reviewers are not asked to infer the job from the diff alone.
A passed test, screenshot, metric, or migration claim has no stable evidence or limitation.
Choose: Add the bounded evidence and limitation, or mark the item not run or unresolved.
Tradeoff: The record may expose more uncertainty, but it stops unsupported status from looking authoritative.
The description starts absorbing project setup or standing contribution policy.
Choose: Keep the change-specific fact and link the maintained README or CONTRIBUTING.md owner.
Tradeoff: Readers make one navigation step, but stable documentation no longer drifts inside individual pull requests.
The template claims review completion, approval, merge readiness, or release authority.
Choose: Remove the claim and leave those decisions to configured reviewers, checks, repository rules, and release owners.
Tradeoff: The PR description remains advisory context, preserving accountable decision boundaries.
START WITH THE AUTHOR RECORD
Download the template and replace every fictional value
Adapt the scope, evidence, tests, risks, migration, rollback, documentation, dependencies, and reviewer guidance to the change your team can actually inspect.
Download the pull request templateThe ZIP is locally reproduced. Public availability and any adapted repository behavior require separate verification.
Inspect the submitted change with the code review checklistUse this page for author context. Use the checklist owner for reviewer inspection, findings, and follow-up.
What a pull request template cannot prove
A complete description improves review context. Its claims remain limited by the actual code, evidence, repository configuration, reviewers, environments, and release process.
- A checked box or author-reported passed test does not prove correctness, complete coverage, CI enforcement, security, accessibility, performance, or compliance.
- A migration or rollback description does not authorize execution, establish production readiness, or prove recovery in the target environment.
- GitHub and GitLab placement, inheritance, variables, and defaults can change; verify current primary documentation and the target repository before rollout.
- The fictional example uses reserved example.test hosts and synthetic identifiers. Replace every record without inserting credentials, private logs, personal data, or unsafe commands.
- This ordinary informational article does not grant AI signup credits or guarantee approval, merge, deployment, reliability, adoption, or business results.
Primary platform guidance and verification sources
The original pack supplies the tested record. GitHub and GitLab primary documentation checked on 2026-08-01 supplies current placement and ownership boundaries without endorsing this article.
[pull-request-pack] Playcode:Pull request template fictional example
Checked August 1, 2026. Supports: The exact same-release fictional record, policy, schema, validator, tests, file allowlist, and authority boundaries.
[github-pull-request-template] GitHub Docs:Creating a pull request template for your repository
Checked August 1, 2026. Supports: GitHub single and multiple pull request template locations, author prompts, default-branch availability, and query-parameter behavior.
[gitlab-description-templates] GitLab Docs:Description templates
Checked August 1, 2026. Supports: GitLab merge request template directory, Markdown extension, default-branch requirement, selection, variables, inheritance, and default priorities.
[github-readme] GitHub Docs:About the repository README file
Checked August 1, 2026. Supports: The README owner boundary for project purpose, usefulness, use, help, maintainers, and links to deeper contribution guidance.
[github-contributing] GitHub Docs:Setting guidelines for repository contributors
Checked August 1, 2026. Supports: The CONTRIBUTING.md owner boundary for standing contribution steps, style, testing, review expectations, and community guidance.
Pull request template questions
Where should a GitHub pull request template go?
GitHub recognizes a single pull_request_template.md in the repository root, docs, or .github directory. Multiple templates can live in a PULL_REQUEST_TEMPLATE subdirectory within supported locations and can be selected with a template query parameter. The template must be merged into the default branch before collaborators can use it.
Where should a GitLab merge request template go?
Store an .md file under .gitlab/merge_request_templates on the default branch. GitLab also supports group and instance templates, variables, quick actions, default-template settings, and inheritance rules. Verify the current GitLab documentation and your plan before relying on those features.
Is a pull request template the same as a code review checklist?
No. The pull request template helps the author provide purpose, scope, evidence, tests, risks, migration, rollback, and reviewer guidance. A code review checklist helps reviewers inspect the actual change and record evidence, findings, and follow-up. Neither record grants approval or merge authority.
Should pull request instructions live in the README?
Keep the README focused on project purpose, use, help, maintainers, and links to deeper documentation. Put standing contribution workflow and rules in CONTRIBUTING.md. Put prompts for one proposed change in the pull request template, and link the maintained owners instead of duplicating them.
Should a pull request template include checkboxes?
Checkboxes can prompt an author to consider required fields, but an unchecked or checked box is not evidence by itself. Record the method, result, evidence reference, environment, and limitation for tests or reviews that matter, and leave enforced status to CI and repository controls.
Can Playcode turn this template into a change workflow?
Playcode can help build a bounded workflow around reviewed change, evidence, test, risk, migration, rollback, documentation, dependency, and reviewer-guidance records. Verify server-side authorization, concurrent updates, audit, provider integration, retention, CI, repository policy, review, release, and recovery ownership before operational use.
BUILD THE BOUNDED WORKFLOW
Turn reviewed change records into a working internal tool
Give Playcode the accepted record model, roles, provider boundaries, checks, and audit needs, then verify access, concurrency, retention, integration, recovery, and release behavior.
Build and verify the workflowThis informational article does not grant AI signup credits. No review, approval, merge, deployment, security, reliability, compliance, or business outcome is guaranteed.