Before looking at where templates live or how GitHub processes them, let’s build a clear picture of what a PR template is and the problem it exists to solve.

What a Pull Request Actually Is, Briefly

A pull request, often shortened to PR, is a proposal on GitHub to merge changes from one branch into another — typically a contributor’s feature branch into a project’s main branch. Every pull request has a title and a description, both editable plain text fields the person opening it fills in, explaining what the change does and why it should be accepted. That description field is exactly where a PR template comes into play.

What a PR Template Is

A PR template is a plain, ordinary Markdown file, stored inside the repository itself, containing pre-written headings, questions, and checklist items meant to guide whoever opens a new pull request. The moment someone starts creating a pull request on a repository that has one, GitHub automatically copies that file’s entire content into the description box before the contributor has typed a single word. Rather than facing a completely blank text field and guessing what information reviewers might want, the contributor sees a ready-made structure — “What does this change do?”, “How was this tested?”, “Related issue” — and simply fills in the blanks or deletes what doesn’t apply.

Why This Small File Has an Outsized Impact

The problem a PR template solves sounds minor in isolation — a poorly described pull request — but multiplied across a busy repository with dozens of contributors and hundreds of pull requests a month, inconsistent, thin descriptions become a genuine, ongoing tax on every reviewer’s time. A reviewer facing a one-line description has to ask basic clarifying questions before real review can even begin, slowing down every single change. A PR template moves that clarifying conversation earlier, embedding it directly into the act of opening the pull request itself, so the information reviewers need is already present by the time they open it, rather than trickling in slowly across several rounds of back-and-forth comments.

PR Templates Versus Other Kinds of GitHub Templates

It’s easy to conflate a PR template with the several other, similarly named templating features GitHub offers, so it’s worth drawing a clear boundary. An issue template plays an almost identical role, but for bug reports or feature requests instead of proposed code changes. A repository template lets someone create an entirely new repository pre-populated with an existing one’s files and structure — a completely different feature aimed at bootstrapping new projects, not describing individual changes. A PR template is narrowly, specifically about the description field of a single pull request, and understanding that narrow scope prevents a lot of confusion when reading GitHub’s own documentation or configuration files, since several of these features share similar naming conventions and nearby configuration locations.

Who Actually Writes and Owns a PR Template

Because a PR template is simply a file committed to the repository, authoring or updating one requires exactly the same permissions as changing any other file in the project — typically write access, often routed through the project’s own normal review process just like any other change. This has a subtle but important consequence: a PR template is never handed down by GitHub itself as a platform default; it always reflects a deliberate choice made by whoever maintains that specific repository, which is exactly why templates vary so widely in tone, length, and content from one project to the next, even though the underlying mechanism is identical everywhere.

GitHub supports several ways to structure PR templates, from a single simple file to a whole library of specialized templates a contributor can choose between. Understanding this layered architecture is key to using the feature well.

The Single Template Setup

The simplest and most common architecture is a single file with a specific, recognized name, placed in one of a small number of recognized locations within the repository — most commonly a hidden configuration folder at the repository root, though a couple of alternative locations are also recognized for convenience. When exactly one such file exists, GitHub applies it automatically and unconditionally to every new pull request opened against that repository, with no extra steps required from the contributor.

The Multiple Template Architecture

Larger or more mature projects often outgrow a single, one-size-fits-all template — a bug fix, a new feature, and a documentation-only change genuinely benefit from different questions being asked. GitHub supports this directly: instead of one file, a repository can maintain a dedicated folder holding several separate template files, each with its own name and its own tailored content. When a contributor creates a new pull request against a repository configured this way, GitHub presents a simple chooser, letting them pick whichever template best matches the kind of change they’re proposing, or select a “blank” option to skip templates entirely if none genuinely fits.

Organization-Wide Templates

Beyond individual repositories, GitHub also allows an entire organization to define default templates in one designated, central repository, which then apply automatically to any of that organization’s other repositories that don’t define their own, more specific template. This layered fallback — a repository’s own template first, then an organization-wide default, then no template at all — lets a company establish a consistent baseline expectation across dozens or hundreds of repositories while still letting individual teams customize further where genuinely needed.

How the Chooser Labels Each Template

When multiple templates exist, the label a contributor sees on the chooser screen isn’t just the raw filename — GitHub looks specifically for a short metadata block at the very top of each template file, letting maintainers assign a clean, human-readable name and a brief description to each option, independent of whatever the underlying file is actually called. This matters more than it might first appear: a well-labeled chooser, with names like “Bug Report” and “New Feature” clearly distinguished from each other, meaningfully reduces the chance a contributor picks the wrong template purely out of confusion about which option applies to their situation.

Interaction With Other Repository Configuration

A PR template doesn’t exist in isolation — it commonly sits alongside several related pieces of repository configuration that shape the same contribution workflow from different angles. A file defining who’s automatically requested as a reviewer for changes to specific parts of the codebase, a file describing broader contribution guidelines, and the PR template itself are often maintained together, in the same hidden configuration folder, as a coordinated set of expectations for anyone proposing a change. None of these files depend technically on one another, but well-run projects tend to keep their messaging consistent across all of them, so a contributor doesn’t receive contradictory guidance from one file to the next.

Let’s trace exactly what GitHub does internally, from the moment a contributor clicks “New pull request” to the moment they see a pre-filled description box.

Step One: Detecting Available Templates

The instant a new pull request creation page is requested, GitHub’s platform checks the target repository’s default branch for any files matching its recognized template locations and names, described in the previous chapter. This check happens on every single new pull request creation, not just once — meaning a template added, edited, or removed takes effect immediately for the very next pull request created afterward, with no separate publishing or activation step required.

Step Two: Resolving Which Template Applies

If GitHub finds exactly one recognized single-template file, that becomes the template, with no further decision needed. If it instead finds a templates folder containing multiple files, it builds a chooser listing every valid template found inside, using each file’s own designated heading or name as the label a contributor sees. If a URL-based template request was included directly in the page’s web address, GitHub skips the chooser and applies that specific template immediately.

flowchart TD
    A["Contributor clicks\nNew pull request"] --> B["GitHub scans default branch\nfor recognized template paths"]
    B --> C{"How many\ntemplates found?"}
    C -->|Zero| D["Description box\nstarts blank"]
    C -->|One| E["Template content\nauto-inserted"]
    C -->|Multiple| F["Chooser screen\nshown to contributor"]
    F --> G["Contributor selects\none template"]
    G --> E
    E --> H["Contributor edits,\nfills in, or deletes sections"]
    H --> I["Pull request opened\nwith completed description"]
    

Step Three: Injecting the Content

Once a template file is identified, GitHub reads its raw Markdown content and inserts it directly into the description field’s editable text area, exactly as written in the file — same headings, same checklist syntax, same placeholder prompts. Nothing about this injection is locked or protected; from that point forward, the contributor is simply editing a normal, fully editable text field that happens to have started out pre-filled rather than empty.

Why the Description Field Remains Fully Free-Form

It’s worth being precise about a common misconception: a PR template is a starting point, not a constraint enforced by GitHub itself. The platform has no built-in mechanism forcing a contributor to keep any particular section, answer any particular question, or leave the checklist items unedited. A contributor can delete the entire template and type something completely different, and GitHub will accept that pull request exactly the same as one that carefully filled in every section. Any actual enforcement of template compliance — checking whether required sections were filled in, or a checklist was genuinely completed — has to be built separately, typically through automated checks, a topic covered fully in the Monitoring, Logging & Metrics chapter.

What Happens When a Contributor Opens a PR Through Other Means

Not every pull request is created through GitHub’s own web interface — many are opened through a command-line tool, a desktop application, or an automated script that creates pull requests as part of a larger workflow. In each of these cases, if the underlying request is routed through GitHub’s own systems to actually create the pull request, the same template-detection logic still applies, and the description field is still pre-filled identically to the web experience. The one meaningful exception is when a tool bypasses the description field entirely by explicitly supplying its own text at creation time — in that specific case, the explicitly supplied text takes priority, and the template is skipped for that particular pull request, exactly as though the contributor had deliberately typed over it themselves.

Let’s trace a complete, realistic journey — from a maintainer writing a template to a contributor’s filled-in pull request reaching a reviewer.

What Happens After the Pull Request Is Opened

Once submitted, the description text behaves exactly like any other pull request description from that point forward — fully editable by the contributor or anyone with appropriate permissions, visible in the pull request’s activity history if changed, and readable by any automated tooling configured to inspect it. The template’s job is essentially finished the moment the pull request is created; everything afterward is ordinary pull request behavior, unrelated to templates specifically.

Editing an Already-Opened Description

It’s worth being clear that the description field remains editable for as long as the pull request itself stays open, and often afterward too. A contributor might return to it hours or days later to add newly discovered context, answer a reviewer’s question directly in the description rather than only in a comment, or update a checklist item once a previously incomplete task is finished. None of these later edits re-trigger anything related to the original template — by this point, the description is simply ordinary, freeform text like any other, with its templated origins no longer tracked or distinguished by GitHub in any special way.

What a Draft Pull Request Changes, and What It Doesn’t

GitHub also allows a pull request to be opened in a deliberately unfinished “draft” state, signaling to reviewers that the work isn’t ready for full review yet. Template behavior is identical either way — the same detection and injection process described earlier runs regardless of whether the contributor is about to open a draft or a fully ready pull request. This is a deliberate design choice: even work still in progress benefits from the same structured prompts, and a contributor can always mark the pull request ready for full review later, at which point reviewers see exactly the same, by-then further-refined description that was shaped by the template from the very start.

A PR template is a genuinely low-cost feature to set up, but it comes with real trade-offs in how much structure to impose and on whom.

The Core Trade-off: Guidance Versus Friction

Every PR template design decision ultimately balances the same two forces: more structure produces more consistently useful descriptions, but every additional required section also adds friction to the simple act of proposing a change. A project fixing typos in documentation and a project shipping safety-critical financial software have very different tolerances for that friction — the right amount of template structure is never universal, but always specific to the actual risk and complexity of the changes a given repository typically receives. A useful way to calibrate this in practice is to periodically imagine the template through the eyes of the smallest, simplest change the project realistically receives — if that trivial change would feel absurd or humiliating to describe using the full template, the template is very likely calibrated toward the project’s largest, most complex changes rather than its everyday, typical ones.

A Second, Quieter Trade-off: Uniformity Versus Nuance

Beyond the more obvious friction trade-off, there’s a subtler one worth naming directly. A template inevitably encodes assumptions about what a “typical” change on this project looks like, and every genuinely unusual change — one that doesn’t fit neatly into the template’s assumed categories — has to either awkwardly force itself into the existing structure or explain, in extra text, why the template doesn’t quite apply this time. This is rarely a serious problem in practice, since most real pull requests do resemble the typical case a well-designed template was built around, but it’s worth maintainers periodically asking whether their template’s assumptions still match the actual range of changes the project receives, rather than assuming the original design remains a perfect fit indefinitely as the project itself evolves.

PR templates aren’t primarily a security feature, but they intersect with real security concerns in a few specific, worth-understanding ways.

Templates as a Structured Prompt for Security-Relevant Disclosure

Many mature projects use a PR template’s checklist specifically to prompt contributors to actively consider security-relevant questions before a change ships — whether new user input is properly validated, whether a dependency was added and needs review, whether any new logging might accidentally capture sensitive data. Used this way, the template functions as a lightweight, consistent nudge toward security-conscious habits, embedded directly into the one moment — opening a pull request — when a contributor’s attention is already focused on describing exactly what their change does.

Never Treat a Template Itself as a Place for Secrets

Because a PR template’s own content becomes visible, by design, to every contributor who opens a pull request — including outside, first-time contributors on a public repository — it should never contain internal credentials, private URLs, or other sensitive operational details, even as example text meant to be replaced. A template is committed to the repository like any other file and is just as permanently part of shared history once merged, exactly as covered for any other accidentally committed sensitive content elsewhere in Git.

Templates and Contributor Trust Levels

On projects that accept contributions from the general public, some teams intentionally use a template’s structure to separate information meant for a trusted maintainer’s eyes from information meant to be public — for example, prompting a contributor to privately report a security vulnerability discovery through a separate, dedicated channel instead of describing it openly inside a public pull request description, where it would be visible to anyone before a fix even ships. This is a case where the template’s wording itself becomes a genuine security control, steering sensitive disclosures away from a fully public space.

Reviewing Automated and Third-Party Pull Requests

An increasingly common scenario worth mentioning is automated tooling — a dependency-update bot, for instance — opening pull requests of its own against a repository. Such tools frequently bypass the human-facing template chooser entirely, since they generate their description programmatically as part of their own automated workflow. Security-conscious teams treat this as a deliberate exception worth watching for: a pull request without the expected template structure, arriving from an automated or unfamiliar account, is sometimes a useful, low-effort signal worth a closer, more careful look before merging, precisely because it deviates from the pattern nearly every genuine human contributor follows.

Because GitHub doesn’t enforce template usage on its own, teams that genuinely want to measure and enforce compliance build additional layers of observation on top of the raw feature.

Automated Description Checks

The most common way teams add real enforcement is through automated checks that run every time a pull request is opened or updated, inspecting the description text directly. Such a check might confirm that specific required headings from the template are still present, that a related-issue reference was actually filled in rather than left as a placeholder, or that every checklist item has genuinely been checked. A pull request failing this automated check can be configured to block merging entirely until it’s corrected, turning a template from a polite suggestion into something closer to an enforced requirement.

Tracking Template Adoption Over Time

Beyond individual pull requests, many teams periodically review how consistently their templates are actually being used and filled in meaningfully across the whole repository — sampling recent pull requests to check whether sections are genuinely completed with useful information, or routinely left as untouched placeholder text. This kind of periodic review often reveals exactly which parts of a template are working well and which are being ignored, informing revisions to the template itself rather than assuming the original design was correct forever.

flowchart LR
    A["PR opened with\ntemplate-based description"] --> B["Automated check reads\ndescription content"]
    B --> C{"Required sections\npresent and filled?"}
    C -->|Yes| D["Check passes;\nmerge allowed"]
    C -->|No| E["Check fails;\nmerge blocked"]
    E --> F["Contributor updates\ndescription"]
    F --> B
    D --> G["Periodic review of\ntemplate adoption trends"]
    

Using Filled-In Templates as a Data Source

Some teams go a step further, treating consistently structured PR descriptions as a genuine data source rather than just readable text — parsing a checklist item’s completion status, or a specific “type of change” field a template asks every contributor to fill in, to automatically generate release notes, tag pull requests by category, or feed lightweight internal dashboards tracking what kinds of changes are shipping and how often. This kind of automation is only possible because the template imposed a predictable, parseable structure in the first place; an unstructured, freeform description offers nothing comparable to extract reliably.

Measuring the Template’s Own Effectiveness

Beyond tracking whether individual pull requests comply with a template, some teams periodically ask a broader, more reflective question: is the template itself actually correlated with better outcomes? A team might compare average review turnaround time, or the frequency of significant back-and-forth revision requests, between pull requests that closely followed the template’s structure and those that mostly ignored it. While this kind of comparison is necessarily informal and rarely rigorous in a small project, it can still surface a genuinely useful signal — if pull requests that follow the template consistently move through review noticeably faster, that’s a strong, concrete argument for investing further in keeping the template well-maintained and worth actually enforcing more strictly going forward.

The Honest Limits of Any Metric Here

It’s worth being candid that every metric described in this chapter measures whether a template’s structure was technically followed, not whether the underlying work it describes was actually done well. A perfectly filled-in template with an honestly incomplete checklist is far more valuable than a template where every box was checked without real verification behind it. The most effective teams treat these metrics as a floor — catching the most obvious, careless omissions — rather than a ceiling, never mistaking full technical compliance with a template for genuine review quality.

A useful discipline some teams adopt is periodically sampling a handful of “compliant” pull requests — ones that technically passed every automated description check — and having a human actually verify whether the underlying claims hold up: did the tests genuinely get added, was the documentation genuinely updated, was the security question genuinely considered rather than reflexively checked. This kind of spot-check doesn’t need to happen often to be valuable; even an occasional audit is usually enough to catch a pattern of careless, box-checking behavior early, well before it becomes a normalized habit across the whole team.

Years of collective experience writing PR templates across countless projects have produced clear, repeatable patterns for what works — and a few traps that keep catching well-intentioned teams.

Proven Patterns

Anti-patterns to Avoid

A distilled checklist for writing and maintaining PR templates that genuinely improve review quality rather than becoming ignored boilerplate.

Best Practices

• Start minimal, then grow deliberately. Begin with a short template covering only the essentials, adding sections later only once a genuine, recurring information gap is identified.
• Write prompts as real questions. “What does this change do, and why?” invites a genuine answer far more effectively than a vague, generic heading like “Description.”
• Revisit the template periodically. Treat it as a living document that should evolve alongside the project’s actual workflow, not a one-time setup task.
• Pair critical checklist items with automated verification. Where a checklist item truly matters, back it with an automated check rather than relying on honesty alone.
• Keep security-sensitive guidance out of the template’s own visible text where it shouldn’t be public. Route genuinely sensitive disclosures to a private channel instead.
• Test the contributor experience yourself. Open a practice pull request occasionally to see exactly what a new contributor sees, catching stale or confusing wording firsthand.
• Explain the “why” behind unusual requirements. A checklist item that seems arbitrary without context is far more likely to be checked off carelessly than one whose purpose is briefly, clearly explained.
• Coordinate template changes like any other repository change. Route significant template revisions through the project’s normal review process, so the people who’ll actually use it get a chance to weigh in first.

Common Mistakes

Seeing how real projects and organizations actually use PR templates day to day makes the abstract concepts concrete.

A PR template is a small, deliberately unglamorous file that quietly shapes one of the most important recurring interactions in modern software development: the moment a contributor explains what a change does before someone else reviews it. By auto-populating a pull request’s description the instant it’s created, GitHub turns a blank, easy-to-underfill text box into a guided structure that consistently surfaces the information reviewers actually need. That structure is entirely a suggestion, not a technical requirement — its real power comes from how naturally people follow a clear prompt already sitting in front of them, and its real limits come from exactly that same fact, which is why teams that need genuine enforcement layer automated checks on top rather than trusting the template alone.

What makes this feature worth understanding thoroughly, rather than treating as a minor configuration detail, is how disproportionate its impact tends to be relative to its cost. Almost nothing else in a typical repository’s setup takes as little effort to create and maintain while so consistently improving the everyday experience of both contributors and reviewers. A thoughtfully written template, kept current and appropriately scoped to the kinds of changes a project actually receives, quietly pays for itself many times over across every single pull request that follows — precisely because it solves the same small, recurring problem, once and reliably, rather than requiring it to be solved fresh by every contributor’s own judgment each time.