GitHub Issue Template: fertige YAML-Formulare + config.yml

Q: Wo liegen GitHub Issue Templates?

In .github/ISSUE_TEMPLATE/ auf dem Standardbranch. Standardvorlagen für die ganze Organisation kommen in denselben Ordner in einem öffentlichen Repository namens .github.

Q: Kann ich ein Issue-Template für alle Repositorys meiner Organisation nutzen?

Ja. Leg die Vorlagen und die config.yml in ein öffentliches .github-Repository. Jedes Repo ohne eigenen ISSUE_TEMPLATE-Ordner nutzt sie.

Q: Wie mache ich ein Feld in einem GitHub Issue Template zur Pflicht?

Füg in einem YAML-Formular required: true unter validations des jeweiligen Felds hinzu. Das blockiert das Absenden nur in öffentlichen Repositorys.

Q: Kann ein GitHub Issue Template Screenshots verlangen?

Ja, in öffentlichen Repos, mit einem upload-Feld, das auf required: true gesetzt ist. In privaten Repos kannst du nur darum bitten und nachhaken.

Q: Hat GitLab Issue Templates?

Ja. GitLabs Description Templates sind Markdown-Dateien in .gitlab/issue_templates/. Ein Gegenstück zu YAML-Formularen gibt es nicht.

Q: Gibt es einen Generator für GitHub Issue Templates?

GitHub hat einen eingebaut: Settings, dann Set up templates. Er erstellt Markdown-Vorlagen, also starte YAML-Formulare mit den Beispielen oben.

Ein GitHub Issue Template ist eine Markdown- oder YAML-Datei im Ordner .github/ISSUE_TEMPLATE deines Repositorys, die neue Issues vorausfüllt oder strukturiert. YAML-Issue-Formulare bringen echte Felder mit: Dropdowns, Checkboxen, Pflichtfelder und ein Upload-Feld für Screenshots. Committe die Datei in den Standardbranch und füg dann eine config.yml hinzu, um die Vorlagenauswahl zu steuern.

Dieser Guide behandelt das Setup im Repo. Für die inhaltliche Seite lies, was Meldende in jedes Feld schreiben sollten.

Was ist ein GitHub Issue Template?

Ein Issue-Template legt fest, was Leute sehen, nachdem sie auf New issue geklickt haben. GitHub unterstützt zwei Arten, und ein Repo kann beide nutzen.

Markdown-Vorlagen vs. YAML-Issue-Formulare

	Markdown-Vorlage	YAML-Issue-Formular
Dateiendung	`.md`	`.yml` oder `.yaml`
Was Meldende bekommen	Ein Textfeld mit vorausgefüllten Überschriften	Getrennte Felder: Text, Dropdowns, Checkboxen, Uploads
Pflichtfelder	Nichts wird erzwungen	`required: true` blockiert das Absenden, nur in öffentlichen Repos
Screenshots	Irgendwo in den Text gezogen	Ein eigenes `upload`-Feld mit einer `accept`-Liste
Reihenfolge in der Auswahl	Nach den YAML-Formularen gelistet	Zuerst gelistet
Status	Stabil	Public Preview, Änderungen möglich

Nutz YAML-Formulare für Bug-Meldungen, so wie Kubernetes in einem dieser Beispiele für technische Dokumentation. Markdown behältst du für weniger strukturierte Themen wie Designnotizen.

Markdown-Issue-Vorlage neben einem YAML-Issue-Formular mit Pflichtfeldern und Upload-Bereich

Wo GitHub Issue Templates liegen

Jede Vorlage liegt in einem Ordner auf deinem Standardbranch:

.github/
└── ISSUE_TEMPLATE/
    ├── 01-bug_report.yml
    ├── 02-feature_request.yml
    └── config.yml

Eine Vorlage auf einem anderen Branch taucht nicht auf. Markdown-Vorlagen brauchen .md. Formulare funktionieren als .yml oder .yaml. Pull Requests nutzen eine eigene Markdown-Datei ohne Formulare, mehr dazu im Leitfaden zum Pull-Request-Template.

Um Vorlagen in einer ganzen Organisation zu teilen, leg ein öffentliches Repository namens .github an und füg ihm denselben Ordner .github/ISSUE_TEMPLATE/ hinzu. GitHub nutzt diese Dateien für jedes Repo im Konto, das keine eigenen Vorlagen hat.

Ein Repo mit einem eigenen, gültigen ISSUE_TEMPLATE-Ordner ignoriert die Standardvorlagen der Organisation komplett. Nichts wird zusammengeführt, wie GitHubs Doku zu Community-Health-Dateien erklärt.

Ordnerstruktur für GitHub Issue Templates in einem Repo und im .github-Repository einer Organisation

So erstellst du ein Issue-Template auf GitHub

Option 1: der Template-Builder (Markdown)

Öffne das Repo und klick auf Settings.
Such unter Features den Eintrag Issues und klick auf Set up templates. Aktiviere zuerst Issues, falls der Button fehlt.
Wähl unter Add template eine Vorlage aus und klick dann auf Preview and edit.
Bearbeite Name, About-Text und Inhalt, dazu optional Titel, Labels und Assignees.
Klick auf Propose changes und committe in den Standardbranch.

Der Builder schreibt die YAML-Front-Matter für dich (name, about, title, labels, assignees). Der Name der Vorlage muss länger als 3 Zeichen sein.

Option 2: ein YAML-Issue-Formular committen

Wähl Add file > Create new file, nenn die Datei .github/ISSUE_TEMPLATE/01-bug_report.yml, füg das Formular unten ein und committe es in den Standardbranch. Jedes Formular braucht name, description und body.

Der name muss über alle Vorlagen hinweg eindeutig und länger als 3 Zeichen sein, sonst erscheint das Formular nicht. Die vollständige Liste der Keys steht in GitHubs Syntax für Issue-Formulare.

Bug-Report als Issue-Formular zum Kopieren (YAML)

Dieses Formular besteht die Validierung gegen das öffentliche JSON-Schema für Issue-Formulare. Pass die Optionen an und füg es dann ein.

name: Bug-Report
description: Etwas ist kaputt. Zeig uns, wie wir es reproduzieren können.
title: "[Bug]: "
labels: ["bug", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Danke für deine Meldung. Bitte nur einen Bug pro Issue.
  - type: textarea
    id: what-happened
    attributes:
      label: Was ist passiert?
      placeholder: Die Gesamtsumme bleibt bei $59.00, nachdem ich auf kostenlose Abholung umgestellt habe.
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Schritte zum Reproduzieren
      description: Starte auf einer bekannten Seite. Eine Aktion pro Zeile.
      placeholder: |
        1. Öffne /checkout mit einem Artikel für $49.00
        2. Stell die Lieferung auf Abholung im Laden (kostenlos) um
        3. Sieh dir die Gesamtsumme an
    validations:
      required: true
  - type: textarea
    id: expected-actual
    attributes:
      label: Erwartet vs. tatsächlich
      placeholder: |
        Erwartet: Gesamtsumme sinkt auf $49.00
        Tatsächlich: Gesamtsumme bleibt bei $59.00
    validations:
      required: true
  - type: dropdown
    id: version
    attributes:
      label: Version
      options:
        - "2.4 (aktuell)"
        - "2.3"
        - Älter
    validations:
      required: true
  - type: dropdown
    id: browsers
    attributes:
      label: Betroffene Browser
      multiple: true
      options:
        - Chrome
        - Firefox
        - Safari
        - Edge
        - Nicht browserspezifisch
  - type: input
    id: page-url
    attributes:
      label: Seiten-URL
      placeholder: https://app.example.com/checkout
  - type: upload
    id: visuals
    attributes:
      label: Screenshots oder Bildschirmaufnahme
      description: Nummeriere die Schritte und zeig auf das fehlerhafte Element.
    validations:
      required: true
      accept: ".png,.jpg,.jpeg,.gif,.mp4,.mov,.webm"
  - type: textarea
    id: logs
    attributes:
      label: Konsolen- oder Server-Logs
      description: Füg den Text ein. Er wird automatisch als Code formatiert.
      render: shell
  - type: checkboxes
    id: checks
    attributes:
      label: Vor dem Absenden
      options:
        - label: Ich habe die bestehenden Issues nach diesem Bug durchsucht.
          required: true
        - label: Ich habe Passwörter, Tokens und persönliche Daten aus Screenshots und Logs entfernt.
          required: true

Keys des YAML-Bug-Report-Formulars, nummeriert den Feldern des gerenderten Issue-Formulars zugeordnet

Warum jedes Feld seinen Platz verdient

Was ist passiert? Eine einzeilige Zusammenfassung, die sich bei der Triage schnell überfliegen lässt.
Schritte zum Reproduzieren: Der nummerierte Platzhalter lenkt auf eine Aktion pro Zeile, dieselbe Regel wie bei einem Testfall.
Erwartet vs. tatsächlich: Der Platzhalter zeigt das zweizeilige Format. Verzichte bei Pflichtfeldern auf value: Vorausgefüllter Text zählt als Antwort, also blockiert required dann nie.
Version und Betroffene Browser: Dropdowns liefern Antworten, nach denen du filtern kannst. Setz numerische Optionen wie "2.3" in Anführungszeichen, sonst besteht das Formular die Validierung nicht.
Seiten-URL und Screenshots: wo es kaputtging, und der visuelle Beweis.
Konsolen- oder Server-Logs: render: shell formatiert eingefügten Text als Code.
Vor dem Absenden: Die zweite Checkbox erinnert ans Schwärzen.

Tipps zur Formulierung für jedes Feld findest du im Guide zur Bug-Report-Vorlage.

Warum Screenshots ein eigenes Upload-Feld bekommen

GitHubs Formularschema hat einen Haken. Sobald eine textarea render nutzt, lässt sie keine Dateianhänge mehr zu. Das Log-Feld kann also keine Bilder aufnehmen.

Ein separates upload-Feld löst das, und accept beschränkt es auf Bilder und Videos. Das Upload-Feld nimmt Bilder bis 10 MB und Videos bis 100 MB an.

Private Repos: required wird nicht erzwungen

Das Schema kennzeichnet required mit „Nur für öffentliche Repositorys.“ In privaten und internen Repos können Leute das Formular mit leeren Feldern absenden. Stütz dich dort auf andere Signale:

Klare Labels und ein kurzes markdown-Intro, das sagt, was du brauchst.
Ein needs-info-Label, das du bei der Triage vergibst.
Eine gespeicherte Antwort (Saved Reply), die nach dem fehlenden Screenshot fragt.

Feature-Request als Issue-Formular zum Kopieren (YAML)

Bei Feature-Requests kommt das Problem vor der Lösung. Das Upload-Feld bleibt hier optional.

name: Feature-Request
description: Schlag eine Idee oder eine Verbesserung vor.
title: "[Feature]: "
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: Welches Problem willst du lösen?
      placeholder: Jeden Montag exportiere ich den Report von Hand, weil...
    validations:
      required: true
  - type: textarea
    id: solution
    attributes:
      label: Vorgeschlagene Lösung
    validations:
      required: true
  - type: textarea
    id: alternatives
    attributes:
      label: Alternativen oder Workarounds, die du ausprobiert hast
  - type: dropdown
    id: impact
    attributes:
      label: Wie stark betrifft dich das?
      options:
        - Wäre schön
        - Bremst mich jede Woche aus
        - Blockiert meine Arbeit
    validations:
      required: true
  - type: upload
    id: mockup
    attributes:
      label: Annotierter Screenshot oder Mockup der Stelle, an die das gehört
      description: Optional. Markiere die Stelle in der aktuellen Oberfläche.

Die Vorlagenauswahl mit config.yml konfigurieren

config.yml liegt im selben Ordner und steuert die Auswahlseite.

blank_issues_enabled: false
contact_links:
  - name: Fragen und Hilfe
    url: https://github.com/your-org/your-repo/discussions
    about: Stell Fragen zur Nutzung in den Discussions, nicht in Issues.
  - name: Sicherheitslücke melden
    url: https://github.com/your-org/your-repo/security/policy
    about: Melde Sicherheitslücken vertraulich. Niemals in einem öffentlichen Issue.
  - name: Kundensupport
    url: https://support.example.com
    about: Fragen zu Konto und Abrechnung gehen an den Support-Desk.

blank_issues_enabled: false blendet das leere Issue für die Rollen Read und Triage aus. Die Rollen Write, Maintain und Admin sehen es weiterhin, gekennzeichnet mit Maintainers only. Das ist so gewollt.
contact_links fügt Buttons hinzu, die Leute woandershin schicken: in die Discussions für Fragen, zu deiner Security Policy für Sicherheitslücken, zu einem Support-Desk für Kunden. Jeder Link braucht name, url und about.

Annotierte Vorlagenauswahl mit nummerierten Optionen für Bug, Feature und Kontaktlinks sowie dem Hinweis Maintainers only

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 39 $ zahlen, für immer besitzen.

Preis und Funktionen ansehen

Labels, Assignees, Projects, Issue-Typen und Titelpräfixe

Top-Level-Keys automatisieren die Triage in dem Moment, in dem ein Issue angelegt wird:

title: "[Bug]: " füllt ein Präfix vor, damit die Issue-Liste leicht zu überfliegen bleibt.
labels vergibt nur Labels, die im Repo schon existieren. Ein fehlendes Label wird übersprungen. Für Standardvorlagen der Organisation legst du das Label im .github-Repo und in jedem Repo an, das es nutzt.
assignees nimmt GitHub-Benutzernamen.
projects nutzt das Format owner/number, etwa your-org/7. Wer das Issue anlegt, braucht Schreibzugriff auf das Project, also nutz für externe Mitwirkende den Auto-Add-Workflow des Projects.
type setzt einen Issue-Typ wie Bug. Issue-Typen werden auf Ebene der Organisation definiert.

Du planst einen Bug Bash? Ein kurzes Formular mit labels: ["bug-bash"] hält alle Meldungen aus der Session in einer gefilterten Liste.

Die Auswahl listet zuerst YAML-Formulare, dann Markdown, jeweils nach Dateiname sortiert. Nummeriere deine Dateien (1-bug.yml, 2-feature.yml). Sobald du 10 oder mehr Vorlagen hast, füll mit Nullen auf (01-, 02-), sonst landen 10- und 11- vor 2-.

So sieht ein gut ausgefülltes GitHub-Issue aus

Das Formular kann nur fragen. Hier ist ein ausgefüllter Bug-Report, mit dem ein Entwickler ohne Rückfrage arbeiten kann. Sein Screenshot folgt der Methode „aufnehmen und annotieren“ aus dem Guide Website annotieren.

Annotierter Screenshot eines Checkout-Bugs mit nummerierten Repro-Schritten, Pfeil, erwartetem Wert und deckenden Schwärzungskästen

Darum funktioniert er:

Nummerierte Marker passen zu den Schritten. Die Marker 1, 2 und 3 entsprechen den drei Repro-Schritten, dieselbe Idee wie bei Schritt-für-Schritt-Anleitungen mit Screenshots.
Ein Pfeil und ein Rahmen um den fehlerhaften Wert, dazu ein kurzes Callout mit der erwarteten Zahl.
Secrets unter deckenden Kästen. In öffentlichen Repos sind hochgeladene Dateien ohne Anmeldung abrufbar. Verdeck Tokens, E-Mail-Adressen und Kundendaten vor dem Upload mit deckenden Kästen, denn Unschärfe und Verpixelung lassen sich rückgängig machen. Mehr dazu im Guide, wie du Text schwärzt.
Fehlertext als Text. Füg den Konsolenfehler in das Log-Feld ein, damit er durchsuchbar ist. Wenn du ihn nur als Bild hast, jag ihn durch ein kostenloses Bild-zu-Text-Tool.
Eine kurze Aufnahme der Reproduktion. Nimm ein GIF auf dem Mac oder unter Windows auf.

Kurzes Repro-GIF: Die Gesamtsumme bleibt bei $59.00, nachdem die Lieferung auf kostenlose Abholung im Laden umgestellt wurde

Dieses Repro-GIF mit 5 Frames ist nach dem Export etwa 19 KB groß, also weit unter dem Limit.

Beachte die Limits für Anhänge: 10 MB für Bilder und GIFs sowie 10 MB für Videos in Kommentaren bei kostenlosen Plänen (100 MB bei bezahlten Plänen). Wenn ein GIF darüber liegt, reduziere die GIF-Dateigröße oder nutz den kostenlosen GIF-Kompressor.

Eine .har-Datei steht nicht auf der Liste der unterstützten Formate, also bitte um eine bereinigte HAR-Datei, gepackt als .zip.

Integrierte Tools können annotieren (Mac, Windows). ScreenSnap Pro bündelt das ganze Set in einer App für Mac und Windows: Zählermarker, Pfeile, Hervorhebungen, Text-Callouts, deckende Kästen, GIF- und Videoaufnahme sowie OCR.

Du kannst das erwartete Design auf dem Bildschirm anpinnen, während du den Bug reproduzierst. Bei Layout-Bugs auf einer öffentlichen Seite nimmt die Funktion Website Capture die ganze Seite über eine URL auf. Sie rendert nur öffentliche URLs, also nutz für localhost, VPN oder Seiten hinter einem Login stattdessen die Scrolling Capture von ScreenSnap Pro in deinem eigenen Browserfenster.

Weitere Optionen: Guides für Vollseiten-Screenshots auf dem Mac und unter Windows.

Zieh die Datei in das Upload-Feld von GitHub, damit GitHub sie hostet. Ein Cloud-Link reicht für einen schnellen Hinweis in Slack, aber diese Uploads werden regelmäßig entfernt, also nutz ihn nie als Beleg im Issue.

Jira-Teams können denselben Ablauf mit Screenshots in Jira nutzen. Wenn deine CI visuelle Regressionstests fährt, häng fehlgeschlagene Diffs ebenfalls hier an.

GitLab Issue Templates

GitLab nennt sie Description Templates. Es gibt sie nur in Markdown, YAML-Formulare fehlen.

Speichere .md-Dateien in .gitlab/issue_templates/ auf dem Standardbranch. Sie erscheinen im Dropdown Choose a template.
Eine Datei namens Default.md füllt jedes neue Issue vor. Gibt es mehrere Standardvorlagen, gewinnt der in den Projekteinstellungen gesetzte (Premium, Ultimate), dann die Default.md der übergeordneten Gruppe, dann die des Projekts selbst.
Gruppenvorlagen (Premium, Ultimate) lassen ein Projekt eine ganze Gruppe bedienen. Ein Owner der Gruppe wählt ein Projekt, das direkt unter der Gruppe liegt. Das geht in der Gruppe unter Settings > General > Templates. Jedes Projekt der Gruppe kann diese Vorlagen dann nutzen.
Quick Actions vergeben Labels und Assignees für das Issue, sofern die Person, die es anlegt, die Berechtigung dazu hat.
Vorlagen können keinen Abschnitt zur Pflicht machen und kein Upload-Feld hinzufügen. Die Vorlage kann nur fragen, also schreib die Bitte in einen HTML-Kommentar unter die Überschrift:

## Schritte zum Reproduzieren
1.

## Screenshots oder Aufnahme
<!-- Zieh annotierte Screenshots oder ein kurzes GIF hierher. Deck Tokens und E-Mail-Adressen vorher mit deckenden Kästen ab. -->

/label ~bug ~needs-triage
/assign @qa-lead

Merge-Request-Vorlagen folgen denselben Regeln in .gitlab/merge_request_templates/. GitLab ergänzt für sie ein paar zusätzliche Regeln auf Basis von Commit-Nachrichten und Branch-Namen.

Alle Regeln stehen in GitLabs Doku zu Description Templates.

Fehlerbehebung: GitHub Issue Template wird nicht angezeigt

Nicht auf dem Standardbranch. Merge zuerst den Branch.
Falscher Pfad oder falsche Endung. Es muss .github/ISSUE_TEMPLATE/ sein, mit .md für Markdown-Vorlagen und .yml oder .yaml für Formulare.
Name zu kurz. name braucht mehr als 3 Zeichen.
Ungültiges YAML oder Schema. GitHub zeigt Fehler an, wenn du das Formular erstellst, speicherst oder ansiehst. Häufige Ursachen sind doppelte id-Werte, yes, true oder Zahlen ohne Anführungszeichen in options und ein Body, der nur aus markdown-Elementen besteht. Sieh dir GitHubs häufige Validierungsfehler an.
Org-Standardvorlagen ignoriert. Das Repo hat einen eigenen ISSUE_TEMPLATE-Ordner, also werden die Standardvorlagen nie geladen.
Leeres Issue weiterhin sichtbar. Du hast Write-Zugriff oder höher.
Pflichtfelder werden nicht erzwungen. Das Repo ist privat oder intern.
Labels fehlen an neuen Issues. Die Labels existieren in diesem Repo noch nicht.

Häufig gestellte Fragen

Wo liegen GitHub Issue Templates?

In .github/ISSUE_TEMPLATE/ auf dem Standardbranch. Standardvorlagen für die ganze Organisation kommen in denselben Ordner in einem öffentlichen Repository namens .github.

Was ist der Unterschied zwischen einem GitHub Issue Template und einem Issue-Formular?

Eine Markdown-Vorlage füllt ein einzelnes Textfeld vor. Ein Issue-Formular ist eine YAML-Datei, die getrennte Felder mit Validierungen rendert. Beide erscheinen in derselben Vorlagenauswahl.

Warum wird mein GitHub Issue Template nicht angezeigt?

Meist liegt die Datei nicht auf dem Standardbranch, der Pfad ist falsch, der name ist zu kurz oder das YAML besteht die Validierung nicht. Sieh dir die Liste zur Fehlerbehebung oben an.

Kann ich ein Issue-Template für alle Repositorys meiner Organisation nutzen?

Ja. Leg die Vorlagen und die config.yml in ein öffentliches .github-Repository. Jedes Repo ohne eigenen ISSUE_TEMPLATE-Ordner nutzt sie.

Wie mache ich ein Feld in einem GitHub Issue Template zur Pflicht?

Füg in einem YAML-Formular required: true unter validations des jeweiligen Felds hinzu. Das blockiert das Absenden nur in öffentlichen Repositorys.

Kann ein GitHub Issue Template Screenshots verlangen?

Ja, in öffentlichen Repos, mit einem upload-Feld, das auf required: true gesetzt ist. In privaten Repos kannst du nur darum bitten und nachhaken.

Hat GitLab Issue Templates?

Ja. GitLabs Description Templates sind Markdown-Dateien in .gitlab/issue_templates/. Ein Gegenstück zu YAML-Formularen gibt es nicht.

Gibt es einen Generator für GitHub Issue Templates?

GitHub hat einen eingebaut: Settings, dann Set up templates. Er erstellt Markdown-Vorlagen, also starte YAML-Formulare mit den Beispielen oben.

Starte mit zwei Dateien

Committe 01-bug_report.yml und config.yml, leg selbst ein Test-Issue an und verfeinere die Labels nach einer Woche mit echten Reports.

Wenn dein Team viele visuelle Bugs meldet, kümmert sich ScreenSnap Pro um die Aufnahme: nummerierte Schritte, Pfeile, deckende Schwärzungskästen, GIFs und OCR in einer App. Es ist ein einmaliger Kauf für 39 $, mit 1 Lizenz für 2 Computer (Mac oder Windows). Preise ansehen.