Pull-Request-Template: 8 Vorlagen für GitHub und GitLab

Ein Pull-Request-Template (auch Pull-Request-Vorlage) ist eine Markdown-Datei, meist .github/pull_request_template.md, die die Beschreibung jedes neuen Pull Requests vorausfüllt. Sie fragt den Autor nach einer Zusammenfassung, dem verknüpften Issue, der Art der Änderung, Testschritten, Vorher-nachher-Screenshots und einer Checkliste. So bekommt jeder Reviewer denselben Kontext.

Hier ist ein minimales Template, das du sofort einfügen kannst. Speichere es als .github/pull_request_template.md in deinem Standardbranch, und jeder neue Pull Request auf GitHub beginnt damit.

## Zusammenfassung
<!-- Was sich geändert hat, in 1 bis 3 Stichpunkten. -->

## Warum
<!-- Das Problem, das hiermit gelöst wird. Verlinke das Issue: Closes #123 -->

## Testanleitung
1.
2.

## Screenshots
<!-- Vorher und nachher bei jeder UI-Änderung. Löschen, falls nicht nötig. -->

## Checkliste
- [ ] Ich habe meinen eigenen Diff geprüft
- [ ] Tests hinzugefügt oder aktualisiert
- [ ] Doku aktualisiert oder nicht nötig

Weiter unten findest du, wo die Datei auf jeder Plattform hingehört, sieben weitere Templates und wie du Screenshots anhängst, denen Reviewer vertrauen können. Du willst den Bug beschreiben und nicht den Fix? Dann nimm eine Bug-Report-Vorlage.

Was ein Pull-Request-Template ist (und was nicht)

Ein PR-Template ist der Anfangstext einer Pull-Request-Beschreibung. Es ist für Reviewer und QA geschrieben. Die Template-Datei wird in dein Repo committet, aber die Beschreibung, die damit entsteht, liegt beim Code-Host und nicht in der Git-Historie.

Ein Issue-Template ist etwas anderes: Jemand füllt es aus, um einen Bug zu melden, bevor es überhaupt Code gibt. Eine Commit-Nachricht beschreibt einen einzelnen Commit, ein Pull Request dagegen die gesamte Änderung. Und ein Pull Request (GitHub, Bitbucket, Azure DevOps) ist dasselbe wie ein Merge Request (GitLab).

Templates sind nur Empfehlungen, jeder kann also einen Abschnitt löschen. Um Regeln durchzusetzen, nutzt du geschützte Branches mit verpflichtenden Reviewern und Checks. Beachte außerdem, dass Pull-Request-Templates auf GitHub reines Markdown sind: YAML-Formulare funktionieren nur für Issues.

Wo du ein Pull-Request-Template auf jeder Plattform speicherst

Die meisten Plattformen lesen das Template aus dem Standardbranch. Ein Template, das nur in deinem Feature-Branch existiert, taucht noch nicht auf.

Pull-Request-Templates auf GitHub

Speichere pull_request_template.md im Root, in docs/ oder in .github/ und merge die Datei in den Standardbranch (GitHub Docs). Für mehrere Templates legst du Dateien wie bugfix.md in .github/PULL_REQUEST_TEMPLATE/ ab. Für Pull Requests gibt es keine Auswahlliste, also wählst du eines über den Query-Parameter template aus:

https://github.com/deine-org/dein-repo/compare/main...dein-branch?quick_pull=1&template=bugfix.md

Für einen organisationsweiten Standard legst du das Template in ein öffentliches Repository namens .github. Diese Standarddateien für die Community gelten für jedes Repository ohne eigenes Template. Im Terminal startet gh pr create --template bugfix.md mit einem bestimmten Template, während --body oder --fill es ersetzt (GitHub CLI Manual).

Merge-Request-Templates in GitLab

Speichere jedes Merge-Request-Template als .md-Datei in .gitlab/merge_request_templates/ im Standardbranch. Jede Datei erscheint mit ihrem Namen im Dropdown Choose a template. So wird eines automatisch eingefügt (GitLab Docs):

• Alle Tarife: Nenne die Datei Default.md.
• Premium und Ultimate: Leg das Standard-Template unter Settings > Merge requests fest. Es hat Vorrang vor Default.md. Gruppen können Templates außerdem projektübergreifend teilen.

Nur das Standard-Template unterstützt Variablen, die GitLab beim ersten Speichern des Merge Requests ersetzt:

Templates können auch Quick Actions wie /label ~bug enthalten, jede in einer eigenen Zeile. GitLab führt sie aus, wenn der Merge Request erstellt wird, sofern du die nötige Berechtigung hast.

Pull-Request-Templates in Bitbucket

Bitbucket Cloud liest .bitbucket/pull_request_template.md (Atlassian Support). Anders als die anderen Plattformen liest Bitbucket den Quellbranch. Ein Branch, der vor dem Template abgezweigt wurde, zeigt es deshalb nicht an. Ohne die Datei gilt die Repo-Einstellung Default description. Auf Data Center nutzt du Repository settings oder Project settings > Description template.

Pull-Request-Templates in Azure DevOps

Azure Repos sucht in .azuredevops/, .vsts/, docs/ und im Root, in dieser Reihenfolge, nach pull_request_template.md oder .txt (Microsoft Learn). Eine Datei unter pull_request_template/branches/feature.md gilt für Pull Requests in feature oder feature/* und hat Vorrang vor dem Standard.

Weitere Dateien in pull_request_template/ erscheinen im Dropdown Add a template, und ?template=name.md in der URL erzwingt eines davon. Ein angewendetes Template ersetzt die Liste der Commit-Nachrichten, und Add commit messages holt sie zurück.

Aufbau eines guten Pull-Request-Templates

Ein gutes Template beantwortet die Fragen, die ein Reviewer sonst in Kommentaren stellen würde:

1. Zusammenfassung: was sich geändert hat, in 1 bis 3 Stichpunkten.
2. Warum und verknüpftes Issue: das Problem plus Closes #123. Ein Schlüsselwort zum Schließen schließt das Issue, sobald der Pull Request in den Standardbranch gemergt wird.
3. Art der Änderung: Feature, Fix, Refactoring, Doku oder Breaking Change.
4. Testanleitung: nummerierte Schritte, denen jeder folgen kann.
5. Screenshots oder Aufnahmen: vorher und nachher für alles Visuelle.
6. Risiko und Rollback: was kaputtgehen könnte und wie du es rückgängig machst.
7. Checkliste: was der Autor schon geprüft hat.

Für Testschritte kannst du eine Regel aus Ashlee Boyers PR-Template übernehmen: Jeder Schritt ist genau eine Aktion oder eine Beobachtung. „Klick auf Speichern“ ist eine Aktion. „Ein grüner Toast erscheint“ ist eine Beobachtung.

Halte das Template unter etwa 25 Zeilen und schreib Hinweise in HTML-Kommentare, damit sie beim Rendern verschwinden. Autoren sollten Abschnitte löschen, die nicht zutreffen.

8 Pull-Request-Template-Beispiele zum Kopieren

Jedes dieser Beispiele bleibt unter 25 Zeilen. Kopier das Beispiel, das zu deiner Änderung passt.

1. Minimales Standard-Template (für jedes Repo)

Nutz das Template vom Anfang dieser Seite. Es passt zu jeder Änderung und ist kurz genug, dass Leute es auch ausfüllen.

2. PR-Template für Features

Für neues Verhalten, das Produktkontext und einen Hinweis zum Rollout braucht.

## Was hinzukommt
<!-- 1 bis 3 Stichpunkte. -->

## Warum
<!-- Closes #123. Verlinke die Spezifikation. -->

## Art der Änderung
- [ ] Neues Feature
- [ ] Breaking Change

## Testanleitung
1.
2.

## Rollout
<!-- Feature Flag, Migration oder "keiner". -->

## Screenshots
<!-- Vorher und nachher, gleicher Ausschnitt. -->

## Checkliste
- [ ] Tests decken den neuen Pfad ab
- [ ] Doku und Changelog aktualisiert

3. PR-Template für Bugfixes

Verlinke den Bug-Report und beweise dann den Fix.

## Bug
Fixes #

## Ursache
<!-- Ein oder zwei Sätze. -->

## Fix
<!-- Was sich geändert hat und warum dieser Ansatz. -->

## Regressionstest
<!-- Der Test, der vor dieser Änderung fehlgeschlagen ist. -->

## Vorher und nachher
<!-- Repro-GIF vorher, dieselben Schritte nachher. -->

## Fehlertext
<!-- Füge den Fehler als Text ein, nicht nur als Bild. -->

## Checkliste
- [ ] Die Repro-Schritte aus dem Issue laufen jetzt durch

Wenn der Fehler nur als Screenshot existiert, macht OCR wieder Text daraus. Sieh dir an, wie du Text aus einem Screenshot auf dem Mac kopierst, oder wirf einen Blick auf die Übersicht zu OCR-Software für Windows.

4. Template für UI- oder Frontend-Änderungen

Reviewer sollten die Änderung sehen, ohne den Branch auszuchecken.

## Zusammenfassung
<!-- Was anders aussieht oder sich anders verhält. -->

Closes #

## Vorher und nachher
| Vorher | Nachher |
| --- | --- |
| <!-- Bild hineinziehen --> | <!-- Bild hineinziehen --> |

## Geprüft auf
- [ ] Desktop 1440px
- [ ] Mobil 375px
- [ ] Dark Mode
- [ ] Nur Tastatur (Fokus sichtbar)
- [ ] Screenreader-Labels

## Testanleitung
1.
2.

5. Template für Hotfixes oder Incidents

Tempo zählt, eine nachvollziehbare Spur aber auch. Mach den Rollback explizit.

## Incident
<!-- Verlinke den Incident oder den Alert. -->

## Auswirkung
<!-- Wer betroffen ist und seit wann. -->

## Änderung
<!-- Der kleinste Fix, der den Schaden stoppt. -->

## Rollback-Plan
<!-- Exakter Revert-Befehl oder Flag. -->

## Verifiziert in
- [ ] Staging
- [ ] Produktion

## Follow-up
<!-- Ticket für den vollständigen Fix. -->

6. PR-Template nur für Dokumentation

Bei Dokus wird die gerenderte Seite geprüft. Der Guide zu Screenshots in technischer Dokumentation zeigt, wie du sie sauber aufnimmst.

## Was sich geändert hat
<!-- Seiten hinzugefügt, verschoben oder neu geschrieben. -->

## Vorschau
<!-- Screenshot oder Vorschau-URL. -->

## Checks
- [ ] Links geprüft
- [ ] Codebeispiele laufen wie beschrieben
- [ ] Screenshots entsprechen der aktuellen Oberfläche
- [ ] Keine Secrets oder Kundendaten in Bildern

7. Template für Open-Source-Beiträge

Externe Mitwirkende kennen deinen Prozess noch nicht, also schreib ihn aus.

## Zugehöriges Issue
<!-- Verlinke es. PRs ohne verknüpftes Issue werden eventuell geschlossen. -->

## Was und warum
<!-- Kurze Beschreibung. -->

## Breaking Change?
- [ ] Ja (beschreibe die Migration)
- [ ] Nein

## Tests
- [ ] Ich habe die Testsuite lokal ausgeführt
- [ ] Ich habe Tests für diese Änderung hinzugefügt

## Rechtliches
- [ ] Ich habe das CLA unterschrieben, oder meine Commits haben ein Sign-off (DCO)

8. GitLab-Merge-Request-Template mit Quick Actions und Variablen

Speichere es als .gitlab/merge_request_templates/Default.md, damit die Variablen ausgefüllt werden. Die Quick Actions setzen beim Erstellen des Merge Requests ein Label, einen Meilenstein und einen Reviewer.

## Zusammenfassung
Mergt %{source_branch} in %{target_branch}.

%{closes_issue}

## Commits
%{all_commits}

## Testanleitung
1.
2.

/label ~"Review nötig"
/milestone %"Sprint 42"
/assign_reviewer @dein-team-lead

So fügst du Screenshots und Aufnahmen zu einem Pull Request hinzu

Ein Diff zeigt, welcher Code sich geändert hat. Ein Screenshot zeigt, was Nutzer sehen werden.

Vorher und nachher mit demselben Ausschnitt aufnehmen

Nimm das „Vorher“ auf main auf, dann denselben Bereich bei gleicher Fenstergröße auf deinem Branch. Auf dem Mac drückst du ⌘ + Shift + 4 (Apple Support). Unter Windows drückst du Win + Shift + S oder nutzt das Snipping Tool.

Diese Aufnahmen zeigen die Änderung, die du beabsichtigt hast. Visual Regression Testing findet die, die du nicht beabsichtigt hast.

Markiere genau, was sich geändert hat

Setz einen Pfeil und eine Hervorhebung auf das geänderte Element. Wenn sich mehreres geändert hat, nutz nummerierte Marker, die zu den Stichpunkten in deiner Zusammenfassung passen. Für geänderte Werte reicht eine kurze Beschriftung, etwa „Padding 8px auf 12px“.

Ein kostenloses Tool zur Bildannotation läuft direkt im Browser, und Combine Images fügt das Paar zu einer Datei zusammen. Weitere Optionen findest du bei den besten Tools zur Bildannotation oder in der Anleitung, wie du Screenshots auf dem Mac annotierst.

Personenbezogene Daten und Secrets vor dem Hochladen schwärzen

Screenshots aus Staging verraten Kunden-E-Mails, Tokens und interne URLs. Deck Secrets und personenbezogene Daten mit einem deckenden, vollflächig gefüllten Kasten ab. Weichzeichnen oder Verpixeln reicht nie: Beides lässt sich bei kurzen Zeichenketten rückgängig machen, wie der Leitfaden zum Schwärzen von Text erklärt.

Schwärze vor dem Hochladen und rotiere jeden echten Token, der zu sehen war. In einem öffentlichen Repo kann jeder mit dem Link einen Anhang öffnen. Wenn du das Bild aus der Beschreibung entfernst, ist die Datei damit nicht unbedingt gelöscht.

Für Interaktionen ein kurzes GIF oder MP4 aufnehmen

Hover-Zustände und mehrstufige Abläufe versteht man in Bewegung besser, also nimm 5 bis 10 Sekunden einer einzelnen Interaktion auf. GitHub akzeptiert GIFs bis 10 MB sowie Videos als .mp4, .mov oder .webm bis 10 MB in kostenlosen Plänen oder bis 100 MB in bezahlten Plänen (GitHub Docs).

Diese Demo ist eine Schleife aus 10 Frames, 6,6 Sekunden lang und als GIF 12 KB groß. Eine echte Bildschirmaufnahme hat viel mehr Frames, prüf also die Dateigröße, bevor du sie hineinziehst. Wie du selbst eines erstellst, erfährst du unter GIFs auf dem Mac aufnehmen oder Bildschirm unter Windows als GIF aufnehmen. Für die Wiedergabe im Browser ist H.264-MP4 besser als MOV (MOV vs. MP4), und wenn das GIF zu groß wird, kannst du die GIF-Dateigröße verringern.

Eine ganze Seite aus einer Deploy-Preview aufnehmen

Tools, die per URL aufnehmen, funktionieren, wenn sich die Deploy-Preview ohne Login öffnen lässt. Hinter SSO oder einem Vorschauschutz führst du Capture full size screenshot über das Befehlsmenü der Chrome DevTools aus oder nimmst die Seite in Abschnitten auf. Mehr dazu in den Anleitungen zu ganzseitigen Screenshots auf dem Mac und unter Windows.

Alles in Markdown anordnen

Zieh Dateien direkt in die Beschreibung, damit GitHub oder GitLab sie zusammen mit dem Pull Request hostet. Leg die Bildgröße mit einem img-Tag fest und pack große Bildsammlungen in einen aufklappbaren Block:

| Vorher | Nachher |
| --- | --- |
| <img width="400" alt="Vorher" src="..."> | <img width="400" alt="Nachher" src="..."> |

<details>
<summary>Weitere Screenshots</summary>
<img width="600" alt="Mobile Ansicht" src="...">
</details>

Wenn du an die meisten Pull Requests Bilder anhängst, hält ScreenSnap Pro (Mac und Windows) den ganzen Ablauf in einer App: Bereichsaufnahme, Pfeile, Zähler und Beschriftungen, Schwärzen mit deckender Füllung sowie Aufnahmen als GIF oder MP4. Außerdem nimmt es ganze Seiten von öffentlichen URLs auf, kopiert Fehlertext per OCR und pinnt die „Vorher“-Aufnahme auf den Bildschirm, während du das „Nachher“ vorbereitest. Häng die gespeicherten Dateien an, denn Cloud-Links eignen sich für einen schnellen Slack-Ping, nicht für die dauerhafte Dokumentation im Pull Request.

Von den Machern dieser Seite

Genug von langweiligen Screenshots? Probier ScreenSnap Pro.

Schöne Hintergründe, professionelle Anmerkungen, GIF-Aufnahme und sofortiges Teilen in der Cloud, alles in einer App. Einmal 34 $ zahlen, für immer besitzen.

Preis und Funktionen ansehen

Pull-Request-Checkliste für Autoren und Reviewer

Ein Template erinnert den Autor. Eine Checkliste hält beide Seiten ehrlich.

Als Autor, bevor du ein Review anforderst:

• Eigenen Diff von oben bis unten gelesen
• Tests laufen durch und decken die Änderung ab
• Doku aktualisiert, wo sich Verhalten geändert hat
• Screenshots bei UI-Änderungen angehängt
• Keine Secrets im Diff, in Logs oder in Bildern
• Eine logische Änderung pro Pull Request

Als Reviewer, bevor du freigibst:

• Die Änderung tut, was die Zusammenfassung sagt
• Tests würden ohne die Änderung fehlschlagen
• Namen sind klar und passen zur Codebasis
• Keine neuen Risiken bei Eingaben, Auth oder Secrets
• Die Oberfläche sieht beim eigenen Testlauf so aus wie auf den Screenshots

Nach dem Merge liefert eine gute Zusammenfassung den Stoff für deine Changelog-Einträge und Release Notes.

Warum dein Pull-Request-Template nicht angezeigt wird

Meist liegt es an einem dieser Punkte:

• Noch nicht im Standardbranch. GitHub, GitLab und Azure DevOps lesen nur den Standardbranch, also merge das Template zuerst.
• Bitbucket liest den Quellbranch. Ältere Branches brauchen ein Rebase, damit sie die Datei sehen.
• Falscher Ordner oder Dateiname. Prüf den Pfad in der Tabelle oben, einschließlich des führenden Punkts.
• Templates in GitHub-Unterordnern werden nicht automatisch eingefügt. Dateien in PULL_REQUEST_TEMPLATE/ laden nur mit ?template=. Behalte zusätzlich eine eigene Standarddatei.
• Ein Branch-Template in Azure hat Vorrang. Ein Treffer in pull_request_template/branches/ ersetzt den Standard.
• Kein Standard in GitLab. Ohne Default.md oder die Projekteinstellung beginnt die Beschreibung leer.
• Der PR wurde mit gh pr create --body oder --fill, über die API oder von einem Bot geöffnet. Diese Wege senden ihren eigenen Text, also lädt das Template nie. Führ gh pr create ohne diese Flags aus oder ergänze --template.

Ersetzen KI-generierte PR-Beschreibungen Templates?

Nicht ganz. GitHub Copilot kann aus dem Diff eine Pull-Request-Zusammenfassung erstellen: einen kurzen Überblick plus eine Liste der wichtigsten Änderungen. Das deckt den Abschnitt Zusammenfassung gut ab.

Copilot ignoriert aber, was schon in der Beschreibung steht, seine Ausgabe folgt also nicht deinen Überschriften. Füg sie selbst unter Zusammenfassung ein. Und kein Modell kann deine Testnachweise liefern: Es hat die Schritte nicht ausgeführt und die Screenshots nicht aufgenommen.

Häufig gestellte Fragen

Was ist ein gutes Pull-Request-Template?

Eines mit höchstens etwa 25 Zeilen, das nach einer Zusammenfassung, dem Grund und dem verknüpften Issue, Testschritten, Vorher-nachher-Screenshots bei UI-Änderungen und einer Checkliste fragt. Hinweise stehen in HTML-Kommentaren, damit sie beim Rendern verschwinden.

Wie erstellst du ein Pull-Request-Template?

Leg pull_request_template.md in .github/, docs/ oder im Root des Repositorys an und merge die Datei in den Standardbranch. In GitLab fügst du .md-Dateien zu .gitlab/merge_request_templates/ hinzu. Bitbucket Cloud nutzt .bitbucket/pull_request_template.md.

Wie schreibst du einen guten Pull Request?

Beschränk ihn auf eine logische Änderung. Erklär, was sich geändert hat und warum, verlinke das Issue, liste Testschritte auf und häng bei allem Visuellen Vorher-nachher-Screenshots an. Prüf vorher deinen eigenen Diff.

Wie erstellst du einen Pull Request?

Push deinen Branch mit git push -u origin dein-branch. Klick dann auf GitHub auf Compare & pull request oder führ im Terminal gh pr create aus. Dein Template füllt die Beschreibung aus.

Was ist der Hauptunterschied zwischen einem Pull Request und einem Merge Request?

Nur der Name. GitHub, Bitbucket und Azure DevOps sagen Pull Request, GitLab sagt Merge Request. Beide bitten jemanden, einen Branch zu prüfen und zu mergen.

Kann ein GitHub-Repo mehrere Pull-Request-Templates haben?

Ja. Leg sie in einen Ordner PULL_REQUEST_TEMPLATE/ und lade eines mit ?template=dateiname.md in der URL. GitHub hat dafür keine Auswahlliste, also teile die Links.

Kann ich ein Pull-Request-Template für eine ganze GitHub-Organisation festlegen?

Ja. Füg pull_request_template.md zu einem öffentlichen Repository namens .github in der Organisation hinzu. Repositorys mit eigenem Template nutzen weiterhin ihr eigenes.

Sollte jeder Pull Request Screenshots enthalten?

Nein. Füg sie hinzu, wenn die Änderung sichtbar ist: UI, E-Mails, Reports oder Doku. Backend-Änderungen brauchen stattdessen Testausgaben und klare Schritte. Lösch einen ungenutzten Abschnitt Screenshots, statt ihn leer stehen zu lassen.

Klein anfangen und das Template wachsen lassen

Arbeite zwei Wochen lang mit dem minimalen Template. Ergänze dann nur die Abschnitte, nach denen Reviewer immer wieder gefragt haben. Das beste Pull-Request-Template ist das, das Leute auch ausfüllen.

Wenn Vorher-nachher-Screenshots zur Gewohnheit werden, erledigt ScreenSnap Pro Aufnahme, Annotation, Schwärzen und GIF-Aufnahme in einer App. Es kostet einmalig 34 $, mit 1 Lizenz für 2 Computer (2 Aktivierungen, Mac oder Windows).