Branch-Naming-Konventionen fürs ganze Team

1. Warum Branch-Naming für die Zusammenarbeit im Team zählt

Ein Git-Repository mit zehn aktiven Entwicklern erzeugt schnell fünfzig oder mehr offene Branches gleichzeitig. Ohne eine verbindliche Namenskonvention entsteht daraus in wenigen Wochen eine Liste, die niemand mehr lesen kann: main, fix, test2, jans-branch, wip-neu, temp-checkout-bug. Jeder dieser Namen zwingt Kolleginnen und Kollegen dazu, den Branch zu öffnen und den Diff zu lesen, nur um herauszufinden, worum es überhaupt geht. Das kostet Zeit, die sich über ein ganzes Team und ein ganzes Jahr gerechnet zu einem spürbaren Produktivitätsverlust summiert.

Eine konsistente Branch-Naming-Konvention löst dieses Problem an der Wurzel, weil sie Informationen direkt in den Namen verlagert, die sonst erst im Code oder im Ticket-System nachgeschlagen werden müssten. Wer den Typ der Änderung, das zugehörige Ticket und eine kurze Beschreibung schon im Branch-Namen sieht, kann Priorität und Kontext auf einen Blick einschätzen, ohne einen einzigen Klick. Das gilt besonders bei Merge Requests, Codereviews und beim Durchsuchen von git branch -a in einem gewachsenen Magento-Projekt mit vielen Modulen.

2. Die Standard-Präfix-Taxonomie: feature/, bugfix/, hotfix/, release/, chore/

Die gängige Präfix-Taxonomie orientiert sich am ursprünglichen Git-Flow-Modell, wird aber in den meisten Teams pragmatisch verschlankt. feature/ kennzeichnet neue Funktionalität, die noch nicht im Hauptzweig existiert, etwa feature/PROJ-123-wishlist-export. bugfix/ steht für die Behebung eines Fehlers, der noch nicht in Produktion ist, während hotfix/ ausschließlich für dringende Korrekturen an bereits live geschalteter Software reserviert bleibt und meist direkt von main statt von einem Entwicklungszweig abzweigt.

release/ markiert einen Branch, der einen konkreten Releasekandidaten stabilisiert, etwa release/2026.08.0, und dient als letzte Qualitätsschleife vor dem Tag. chore/ fasst Wartungsarbeiten zusammen, die keine fachliche Funktionalität verändern, etwa Abhängigkeits-Updates oder CI-Konfiguration. Wichtig ist weniger die exakte Liste der Präfixe als die Konsistenz: Jedes Team sollte sich auf eine feste, dokumentierte Menge einigen und diese nicht durch Synonyme wie feat/ neben feature/ verwässern, weil genau solche Varianten spätere Automatisierung unnötig verkomplizieren.

#!/usr/bin/env bash
# Examples of correctly named branches following the team convention
# Pattern: <prefix>/<TICKET-ID>-<short-kebab-case-description>

git checkout -b feature/PROJ-123-add-wishlist-export
git checkout -b bugfix/PROJ-456-cart-total-rounding
git checkout -b hotfix/PROJ-901-checkout-500-error
git checkout -b release/2026.08.0
git checkout -b chore/PROJ-234-upgrade-composer-deps

# Allowed exception prefixes (not deployed, not tracked in CI)
git checkout -b spike/evaluate-redis-session-storage
git checkout -b wip/max-quick-prototype

# Rename an existing, badly named branch to match the convention
git branch -m fix-stuff bugfix/PROJ-456-cart-total-rounding
git push origin -u bugfix/PROJ-456-cart-total-rounding
git push origin --delete fix-stuff

3. Ticket-ID-basierte Benennung für Nachvollziehbarkeit

Ein Präfix allein sagt nur, welche Art von Änderung ein Branch enthält, nicht welche konkrete Anforderung dahintersteht. Erst die Kombination mit einer Ticket-ID aus dem Issue-Tracker macht einen Branch-Namen wirklich rückverfolgbar: feature/PROJ-123-add-wishlist-export verweist eindeutig auf ein Ticket in Jira oder GitHub Issues und lässt sich von dort aus per Klick öffnen, wenn die Tracker-Integration entsprechend konfiguriert ist. Jira erkennt Branch-Namen mit gültiger Projekt-ID automatisch über Smart Commits und verknüpft sie im Entwicklungspanel des Tickets mit Commits, Pull Requests und Deployments.

Diese Rückverfolgbarkeit zahlt sich vor allem Monate später aus, wenn ein Bug in Produktion auf einen bestimmten Commit zurückgeführt werden muss. Ohne Ticket-ID im Branch-Namen bleibt oft nur eine mühsame Suche durch Commit-Historien und Chat-Nachrichten. Mit ihr genügt ein Blick auf git log --grep oder git branch --contains, um den fachlichen Kontext, die ursprüngliche Anforderung und die verantwortliche Person direkt im Tracker wiederzufinden, ganz ohne zusätzliche Dokumentation im Code selbst.

4. Wie uneinheitliche Namen CI-Automatisierung brechen

CI/CD-Pipelines werden in der Praxis häufig über Branch-Namensmuster gesteuert: Ein Push auf einen Branch, der dem Muster release/* entspricht, löst einen Staging-Deploy aus, ein Push auf hotfix/* triggert eine beschleunigte Pipeline mit reduzierter Testmatrix für dringende Fixes. Diese Regeln funktionieren nur zuverlässig, wenn jeder Branch tatsächlich dem erwarteten Muster folgt. Ein Branch namens hotfix-schnell statt hotfix/PROJ-456-schnell wird von einer Regel wie ^hotfix/ nicht erkannt und durchläuft im schlimmsten Fall die volle, langsame Standard-Pipeline oder gar keine Pipeline.

Noch gravierender wird es, wenn Deployment-Regeln an Branch-Präfixe gekoppelt sind: Manche Setups deployen automatisch aus release/*-Branches auf ein Staging-System. Ein uneinheitlich benannter Branch wie neuer-release-branch löst dann keinen Deploy aus, während ein versehentlich falsch benannter Branch wie release/experiment ungewollt in eine produktionsnahe Umgebung gelangen kann. Beide Szenarien untergraben das Vertrauen in die Automatisierung und führen dazu, dass Teams zusätzliche manuelle Kontrollen einbauen, die die eigentliche Automatisierung wieder aushebeln.

# .gitlab-ci.yml (excerpt) - deploy only from branches matching the convention
stages:
  - test
  - deploy

deploy_staging:
  stage: deploy
  rules:
    # Only trigger for release/YYYY.MM.N branches
    - if: '$CI_COMMIT_BRANCH =~ /^release\/[0-9]{4}\.[0-9]{2}\.[0-9]+$/'
  script:
    - ./bin/deploy.sh staging "$CI_COMMIT_BRANCH"

deploy_hotfix:
  stage: deploy
  rules:
    # Fast-tracked pipeline for urgent production fixes
    - if: '$CI_COMMIT_BRANCH =~ /^hotfix\/[A-Z]+-[0-9]+-[a-z0-9-]+$/'
  script:
    - ./bin/deploy.sh production-hotfix "$CI_COMMIT_BRANCH" --skip-slow-tests

reject_unmatched_branch:
  stage: test
  rules:
    - if: '$CI_COMMIT_BRANCH !~ /^(feature|bugfix|hotfix|chore|release|spike|wip)\//'
  script:
    - echo "Branch name does not match any known convention, failing the pipeline"
    - exit 1

5. Automatisiertes Branch-Cleanup und Stale-Branch-Erkennung

Automatisiertes Branch-Cleanup basiert meist auf einer Kombination aus Merge-Status und Alter: Ein Skript listet alle Branches, die seit einer definierten Frist keinen neuen Commit erhalten haben, und markiert sie zur Löschung. Ohne Namenskonvention lässt sich in diesem Prozess nicht unterscheiden, ob ein alter Branch ein vergessenes Experiment ist oder ein bewusst lange offen gehaltener release/-Branch, der auf einen verzögerten Go-Live wartet. Das Cleanup-Skript muss dann entweder riskant automatisch löschen oder bei jedem Kandidaten manuell nachfragen, was den Automatisierungsgewinn zunichtemacht.

Mit einer konsistenten Konvention lassen sich Cleanup-Regeln präzise formulieren: feature/- und bugfix/-Branches werden nach dem Merge automatisch gelöscht, release/-Branches erst nach dem entsprechenden Tag, und Branches ohne erkennbares Präfix werden gesondert markiert und einem Menschen zur Prüfung vorgelegt, statt sie stillschweigend zu ignorieren oder zu löschen. Die Ticket-ID im Namen erlaubt zusätzlich, den Merge-Status direkt mit dem Ticket-Status im Tracker abzugleichen und verwaiste Branches zu erkennen, deren zugehöriges Ticket längst geschlossen wurde.

#!/usr/bin/env bash
# cleanup-stale-branches.sh - convention-aware automated branch cleanup
set -euo pipefail

readonly STALE_DAYS=60
readonly PROTECTED_PATTERN='^(main|develop|release/)'

git fetch --prune origin

while IFS= read -r branch; do
  # Skip protected branches entirely
  [[ "$branch" =~ $PROTECTED_PATTERN ]] && continue

  last_commit_epoch="$(git log -1 --format=%ct "origin/$branch")"
  age_days=$(( ( $(date +%s) - last_commit_epoch ) / 86400 ))

  if (( age_days < STALE_DAYS )); then
    continue
  fi

  # Only auto-delete branches that follow the convention and are merged
  if [[ "$branch" =~ ^(feature|bugfix|chore)/[A-Z]+-[0-9]+- ]] \
     && git branch -r --merged origin/main | grep -q "origin/$branch"; then
    echo "[CLEANUP] Deleting merged, stale branch: $branch ($age_days days old)"
    git push origin --delete "$branch"
  else
    echo "[REVIEW] Unmatched or unmerged stale branch, flagging for manual review: $branch"
  fi
done < <(git branch -r --format='%(refname:short)' | sed 's#^origin/##')

6. Konventionen per Naming-Check-Hook durchsetzen

Eine Konvention, die nur in einem Wiki-Artikel steht, wird in der Praxis regelmäßig ignoriert, besonders unter Zeitdruck. Ein Naming-Check-Hook macht die Regel technisch verbindlich, statt sie auf Disziplin zu verlassen. Ein clientseitiger pre-push-Hook prüft den Branch-Namen gegen eine reguläre Ausdrucksregel, bevor der Push überhaupt das Netzwerk verlässt, und gibt bei einem Verstoß eine klare Fehlermeldung mit einem korrekten Beispiel aus. Der Nachteil: Clientseitige Hooks liegen in .git/hooks, werden nicht automatisch mit dem Repository ausgeliefert und lassen sich von jedem Entwickler umgehen oder deaktivieren.

Für verbindliche Durchsetzung im ganzen Team braucht es zusätzlich eine serverseitige Prüfung. GitLab bietet dafür Push Rules mit einem konfigurierbaren Branch-Namens-Regex direkt in den Projekteinstellungen, GitHub erreicht dasselbe über eine Ruleset- oder Branch-Protection-Regel in Kombination mit einem Status-Check in der CI-Pipeline, der bei einem ungültigen Namen fehlschlägt und den Merge blockiert. Die Kombination aus lokalem Hook für schnelles Feedback und serverseitiger Prüfung als letzter Instanz deckt beide Fälle zuverlässig ab.

#!/usr/bin/env bash
# .git/hooks/pre-push - validates branch names before they leave the machine
set -euo pipefail

# Allowed patterns: feature/, bugfix/, hotfix/, chore/, release/, spike/, wip/
readonly PATTERN='^(feature|bugfix|hotfix|chore)/[A-Z]+-[0-9]+-[a-z0-9-]+$'
readonly RELEASE_PATTERN='^release/[0-9]{4}\.[0-9]{2}\.[0-9]+$'
readonly EXCEPTION_PATTERN='^(spike|wip)/[a-z0-9-]+$'

branch="$(git symbolic-ref --short HEAD)"

if [[ "$branch" == "main" || "$branch" == "develop" ]]; then
  exit 0
fi

if [[ "$branch" =~ $PATTERN ]] || [[ "$branch" =~ $RELEASE_PATTERN ]] || [[ "$branch" =~ $EXCEPTION_PATTERN ]]; then
  exit 0
fi

echo "[ERROR] Branch name '$branch' violates the naming convention." >&2
echo "        Expected: feature|bugfix|hotfix|chore/TICKET-ID-short-description" >&2
echo "        Example:  feature/PROJ-123-add-wishlist-export" >&2
echo "        See CONTRIBUTING.md for the full convention and exceptions." >&2
exit 1

7. Konvention dokumentieren und neue Entwickler onboarden

Eine Namenskonvention ohne dokumentierte Referenz führt zu endlosen Diskussionen darüber, welches Präfix in welchem Fall korrekt ist. Die Konvention gehört in die CONTRIBUTING.md im Repository-Root, wo sie direkt neben den Commit-Message-Regeln und dem Pull-Request-Prozess steht und bei jedem Klonen des Repositories sichtbar ist, statt in einem separaten Wiki zu verstauben, das nach einigen Monaten veraltet. Eine Tabelle mit Präfix, Bedeutung und konkretem Beispiel reicht meist aus, ergänzt um den exakten Regex, den auch der Naming-Check-Hook verwendet.

Beim Onboarding neuer Entwickler zahlt sich diese Dokumentation sofort aus: Statt die Konvention mündlich zu erklären und zu hoffen, dass sie hängen bleibt, verweist man auf die CONTRIBUTING.md und lässt den ersten eigenen Branch direkt vom Hook validieren. Scheitert der erste Push an der Namensregel, liefert die Fehlermeldung des Hooks im Idealfall bereits den Link zur Dokumentation und ein korrektes Beispiel, sodass der neue Kollege die Konvention ohne Rückfrage selbst korrigieren kann.

; .branchlintrc - shared naming rules used by pre-push hook and CI
[patterns]
feature = ^feature/[A-Z]+-[0-9]+-[a-z0-9-]+$
bugfix  = ^bugfix/[A-Z]+-[0-9]+-[a-z0-9-]+$
hotfix  = ^hotfix/[A-Z]+-[0-9]+-[a-z0-9-]+$
chore   = ^chore/[A-Z]+-[0-9]+-[a-z0-9-]+$
release = ^release/[0-9]{4}\.[0-9]{2}\.[0-9]+$

[exceptions]
spike = ^spike/[a-z0-9-]+$
wip   = ^wip/[a-z0-9-]+$

[protected]
branches = main,develop

[options]
case_sensitive_ticket_prefix = true
max_description_length = 50

8. Ausnahmen und Sonderfälle: Spikes, Experimente, persönliche Branches

Keine Konvention passt ohne Ausnahmen auf jeden Anwendungsfall. Kurze Experimente, technische Spikes oder Proof-of-Concepts, die nie gemerged werden sollen, passen schlecht in ein Schema, das auf Ticket-Rückverfolgbarkeit ausgelegt ist. Für solche Fälle bewährt sich ein eigenes, bewusst lockereres Präfix wie spike/ oder experiment/, das im Naming-Check-Hook als gültig anerkannt wird, aber gleichzeitig automatisch von Deployment-Pipelines und Release-Prozessen ausgeschlossen bleibt.

Persönliche Branches für schnelles lokales Ausprobieren sind ein weiterer Grenzfall. Statt sie komplett von der Konvention auszunehmen, empfiehlt sich ein Präfix mit Namenskürzel wie wip/max-, das klar signalisiert, dass der Branch nicht für Reviews oder Deployments gedacht ist. Der Hook sollte solche Ausnahmen explizit über eine kurze Whitelist an erlaubten Zusatz-Präfixen abbilden, statt die Regex so weit aufzuweichen, dass sie am Ende auch beliebige Namen durchlässt. Jede Ausnahme sollte in der CONTRIBUTING.md genauso dokumentiert sein wie die Hauptregel.

9. Typische Stolperfallen und Branch-Namen im Vergleich

In der Praxis wiederholen sich dieselben Stolperfallen: ein Präfix ohne Ticket-ID, ein Ticket-ID-Format, das nicht zum tatsächlichen Projektkürzel im Tracker passt, oder Groß- und Kleinschreibung, die zwischen Branches inkonsistent verwendet wird. Jede dieser Abweichungen wirkt für sich harmlos, summiert sich aber zu genau den Problemen bei CI-Automatisierung und Cleanup, die in den vorherigen Abschnitten beschrieben wurden. Die folgende Tabelle stellt typische unklare Branch-Namen den empfohlenen, konventionsgerechten Varianten gegenüber.

In modernen Git-Workflows ist die Namenskonvention keine Formalität, sondern die Datenbasis, auf der CI-Regeln, Deployment-Trigger und Cleanup-Skripte aufbauen. Wer die Empfehlungen aus der Tabelle konsequent umsetzt und über einen Naming-Check-Hook technisch absichert, bekommt dieselbe Konsistenz automatisch bei jedem neuen Branch, ohne bei jedem Pull Request manuell nachzuprüfen.

10. Zusammenfassung

Die Branch-Naming-Konvention fürs ganze Team löst ein Problem, das ohne sie fast unsichtbar bleibt, bis es teuer wird: fehlende Rückverfolgbarkeit, brüchige CI-Automatisierung und riskantes Branch-Cleanup. Präfixe wie feature/, bugfix/, hotfix/, release/ und chore/ klassifizieren die Art der Änderung, während eine Ticket-ID wie PROJ-123 die Verbindung zum Issue-Tracker herstellt. Zusammen ergeben beide Bestandteile einen Branch-Namen, den CI-Pipelines per Regex zuverlässig auswerten und Cleanup-Skripte sicher automatisieren können.

Der entscheidende Hebel für Durchsetzung ist nicht Disziplin, sondern Technik: Ein Naming-Check-Hook, lokal als pre-push und serverseitig als Push Rule oder Status-Check, verhindert regelwidrige Branch-Namen von Anfang an. Dokumentiert in der CONTRIBUTING.md und mit klar definierten Ausnahmen für Spikes und persönliche Branches bleibt die Konvention praxistauglich, statt an Sonderfällen zu scheitern.

11. FAQ: Branch-Naming-Konventionen fürs ganze Team