Die CODEOWNERS-Datei sinnvoll einsetzen

1. Was die CODEOWNERS-Datei macht und warum sie Reviews automatisiert

Die CODEOWNERS Datei ist eine einfache Textdatei, die GitHub, GitLab und Bitbucket nativ auswerten, um bei jedem Pull oder Merge Request automatisch die passenden Reviewer vorzuschlagen. Statt dass jemand manuell überlegt, wer für einen geänderten Ordner zuständig ist, gleicht die Plattform die geänderten Dateipfade gegen die Regeln in der Datei ab und fügt automatisch die hinterlegten Personen oder Teams als Reviewer hinzu. Es ist kein zusätzliches Tool und kein Bot nötig, die Funktion ist fest in die Plattform integriert.

Der eigentliche Wert entsteht erst im Team-Alltag: Wissen über bestimmte Bereiche, etwa das Checkout-Modul oder die CI-Pipeline, bleibt an den Code gebunden statt in den Köpfen einzelner Personen zu verschwinden. Neue Teammitglieder sehen sofort, wer bei Fragen zu einem Modul der richtige Ansprechpartner ist, und Reviews landen zuverlässig bei jemandem mit tatsächlichem Kontext statt zufällig beim nächsten verfügbaren Kollegen. Gerade bei wachsenden Repositories mit mehreren Teams verhindert das viele oberflächliche Reviews, die inhaltlich wenig Substanz bringen.

2. Speicherort und Dateiformat: GitHub, GitLab und Bitbucket im Vergleich

GitHub sucht die Datei an genau drei möglichen Orten: im Root-Verzeichnis als CODEOWNERS, unter docs/CODEOWNERS oder unter .github/CODEOWNERS. Existieren mehrere dieser Dateien gleichzeitig, verwendet GitHub ausschließlich die zuerst gefundene in dieser Reihenfolge, die anderen werden komplett ignoriert. In der Praxis hat sich .github/CODEOWNERS als Konvention durchgesetzt, weil sie zusammen mit Workflows und Issue-Templates im selben versteckten Ordner liegt und dadurch leichter auffindbar bleibt.

GitLab erlaubt dieselben drei Pfade und ergänzt zusätzlich .gitlab/CODEOWNERS, unterstützt aber zusätzlich benannte Abschnitte mit eckigen Klammern, über die sich verschiedene Genehmigungsgruppen mit eigener Mindestanzahl an Reviewern definieren lassen. Bitbucket Cloud verlangt die Datei ausschließlich im Root-Verzeichnis unter dem Namen CODEOWNERS. Wer mehrere Plattformen parallel nutzt, etwa GitHub für Open-Source-Spiegelungen und GitLab intern, sollte sich auf einen einzigen Speicherort festlegen und dokumentieren, damit niemand versehentlich eine zweite, wirkungslose Kopie pflegt.

3. Syntax und Path-Matching: Glob-Pattern und die Precedence-Regel

Jede Zeile der CODEOWNERS Datei besteht aus einem Pfadmuster gefolgt von einem oder mehreren Owner-Einträgen, getrennt durch Leerzeichen. Die Pfadmuster folgen derselben Glob-Syntax wie .gitignore: ein Sternchen steht für beliebige Zeichen innerhalb eines Pfadsegments, ein doppeltes Sternchen für beliebige Verschachtelungstiefe, und ein abschließender Schrägstrich markiert ein Verzeichnis samt allem Inhalt. Kommentare beginnen mit einer Raute, Leerzeilen werden ignoriert.

Der wichtigste und zugleich am häufigsten missverstandene Mechanismus ist die Precedence-Regel: Nicht das speziellste Muster gewinnt, sondern schlicht das letzte Muster in der Datei, das auf einen Pfad passt. Wer eine allgemeine Regel für app/code/** oben definiert und darunter eine spezifischere für ein einzelnes Modul, muss die spezifischere zwingend weiter unten platzieren, sonst wird sie von der allgemeinen Regel überschrieben, obwohl sie im Diff als vermeintlich präziser erscheint. Diese Reihenfolge-Logik unterscheidet CODEOWNERS von den meisten anderen Konfigurationsformaten mit Glob-Mustern.

# CODEOWNERS: rules are evaluated top to bottom,
# but the LAST matching pattern wins, not the most specific one

# Default fallback owner for everything not matched below
*                           @mironsoft/backend-team

# Frontend team owns all Hyva theme templates and styles
/app/design/frontend/**    @mironsoft/frontend-team

# A more specific override MUST come after the broader rule above,
# otherwise the broader rule silently wins for this path
/app/design/frontend/Mironsoft/default/web/tailwind/**  @mironsoft/frontend-lead

4. Negation, Wildcards und die Grenzen des Pattern-Matchings

Anders als .gitignore unterstützt die CODEOWNERS Syntax kein Ausrufezeichen zur Negation. Es gibt keine Möglichkeit, eine Datei explizit von einer zuvor definierten Owner-Zuweisung auszunehmen. Der einzige Weg, einen Unterpfad von einer allgemeinen Regel auszuschließen, ist eine speziellere Regel weiter unten in der Datei zu platzieren, die für diesen Pfad greift, notfalls sogar mit einem leeren Owner-Feld, wodurch für diesen Bereich schlicht keine automatische Zuweisung mehr stattfindet.

Bei Wildcards lohnt sich Präzision: Ein einzelnes Sternchen matcht nicht über Verzeichnisgrenzen hinweg, für rekursives Matching über beliebig viele Ebenen ist immer das doppelte Sternchen nötig. Ein führender Schrägstrich verankert das Muster am Repository-Root, fehlt er, matcht das Muster den angegebenen Namen an jeder Stelle im Baum, was bei generischen Namen wie config oder tests überraschend viele Treffer erzeugen kann. Ein kurzer Test mit der GitHub-Weboberfläche unter Einstellungen zeigt vor dem Commit zuverlässig, welche Pfade eine Regel tatsächlich erfasst.

5. CODEOWNERS mit Branch Protection kombinieren, damit sie wirklich greift

Ohne zusätzliche Konfiguration ist die CODEOWNERS Datei rein informativ: Die vorgeschlagenen Reviewer werden automatisch hinzugefügt, aber niemand hindert einen Merge daran, auch ohne deren Freigabe durchgeführt zu werden. Gerade unter Zeitdruck wird ein vorgeschlagener Reviewer dann schnell wieder entfernt oder schlicht ignoriert, und die Datei verliert praktisch jede Wirkung. Erst die Kombination mit einer verbindlichen Regel macht aus dem Vorschlag eine tatsächliche Voraussetzung für den Merge.

Auf GitHub aktiviert man dazu in den Branch Protection Rules für den Zielbranch die Option Require review from Code Owners zusätzlich zur allgemeinen Mindestanzahl an Approvals. Auf GitLab findet sich die entsprechende Einstellung unter den Merge Request Approval Settings als Require approval from code owners, kombinierbar mit einer projektweiten oder gruppenweiten Regel. In beiden Fällen kann ein Merge erst dann abgeschlossen werden, wenn mindestens eine Person aus jeder betroffenen CODEOWNERS Zeile tatsächlich zugestimmt hat, unabhängig davon, wie viele andere Kollegen bereits ein allgemeines Approval gegeben haben.

{
  "required_status_checks": null,
  "enforce_admins": true,
  "required_pull_request_reviews": {
    "required_approving_review_count": 1,
    "require_code_owner_reviews": true,
    "dismiss_stale_reviews": true
  },
  "restrictions": null
}

6. Teams versus Einzelpersonen als Code Owner

CODEOWNERS Einträge können sowohl auf einzelne Benutzernamen mit vorangestelltem At-Zeichen als auch auf ganze Teams im Format @organisation/team-name verweisen. Teams haben einen entscheidenden Vorteil: Fällt eine Person durch Urlaub oder Krankheit aus, springt automatisch ein anderes Teammitglied ein, ohne dass die Datei angepasst werden muss. Einzelpersonen als alleinige Owner erzeugen dagegen schnell einen Flaschenhals, besonders bei Modulen mit hoher Änderungsfrequenz, weil jeder Merge auf die Verfügbarkeit genau dieser einen Person wartet.

Voraussetzung für Teams als Owner ist, dass sie tatsächlich Schreibzugriff auf das Repository besitzen, sonst tauchen sie in der Owner-Zuweisung zwar auf, können aber technisch nicht als Reviewer hinzugefügt werden und die Regel läuft ins Leere. Für hochkritische, selten geänderte Pfade wie Zahlungsabwicklung oder Sicherheitskonfiguration bleibt trotzdem oft eine benannte Einzelperson oder ein sehr kleines Team sinnvoll, weil dort bewusst nicht jedes Teammitglied automatisch Freigabekompetenz haben soll.

7. Praxisbeispiel: CODEOWNERS für ein Magento 2 / Hyvä Projekt

In einem Magento 2 Projekt mit Hyvä Theme lassen sich Owner sinnvoll entlang der fachlichen Verantwortung verteilen: Das Frontend-Team übernimmt app/design/frontend/**, während das Backend-Team für app/code/Vendor/**/** zuständig ist. Besonders sensible Pfade wie db_schema.xml Dateien, die Datenbankänderungen deklarativ beschreiben, sollten zusätzlich vom Lead Developer abgedeckt werden, weil fehlerhafte Schema-Änderungen im schlimmsten Fall zu Datenverlust führen können. Auch CI/CD-Konfigurationsdateien verdienen eine eigene, engere Owner-Zuweisung.

Der Grund für die separate Regel bei .github/workflows/** oder .gitlab-ci.yml ist simpel: Änderungen an der Pipeline betreffen potenziell jeden Deploy und jedes andere Teammitglied, weshalb dort typischerweise die Person zuständig sein sollte, die die Infrastruktur verantwortet, unabhängig davon, wer den fachlichen Code darum herum ändert. Diese granulare Aufteilung sorgt dafür, dass ein reiner Frontend-Commit im Template-Ordner nicht unnötig auf ein Review vom Backend-Lead wartet, während ein Schema-Update zuverlässig die richtige Person erreicht.

# .github/CODEOWNERS for a Magento 2 / Hyva project

# Fallback: platform/backend team reviews everything by default
*                                            @mironsoft/backend-team

# Hyva theme: templates, layout XML and Tailwind config
/app/design/frontend/Mironsoft/default/**   @mironsoft/frontend-team

# Custom modules: module owner reviews module-specific logic
/app/code/Mironsoft/SeoSuite/**             @mironsoft/seo-module-owner
/app/code/Mironsoft/Core/**                 @mironsoft/backend-lead

# Declarative schema changes always need the lead developer,
# a broken db_schema.xml can cause data loss on deploy
**/db_schema.xml                            @mironsoft/lead-dev

# Pipeline and deployment config: infrastructure owner only
/.github/workflows/**                       @mironsoft/devops-lead
/.gitlab-ci.yml                             @mironsoft/devops-lead

8. Häufige Fallstricke beim Einsatz von CODEOWNERS

Der häufigste Fallstrick ist Verwaisung: Verlässt eine Person das Team oder wechselt die Rolle, bleibt ihr Benutzername in der Datei stehen, bis jemand aktiv aufräumt. GitHub und GitLab liefern dafür keine automatische Warnung, die Regel bleibt einfach bestehen und schlägt bei jedem passenden Pull Request fehl, weil ein ehemaliges Mitglied ohne Zugriff nicht als Reviewer hinzugefügt werden kann. Ein zu breit gefasstes Muster wie ein einzelner Stern für das gesamte Repository erzeugt zusätzlich einen Flaschenhals, wenn plötzlich jeder Merge auf dieselbe kleine Gruppe wartet.

Der zweite große Fallstrick sind stille Syntaxfehler: Ein Tippfehler im Benutzernamen, ein fehlendes At-Zeichen oder ein falsch geschriebener Pfad führt nicht zu einer Fehlermeldung, die Zeile matcht einfach nichts und die Zuweisung bleibt aus, ohne dass irgendjemand das bemerkt. Auch Groß- und Kleinschreibung ist relevant: Pfadmuster sind case-sensitive, während Benutzernamen es je nach Plattform nicht sind, was bei manueller Pflege regelmäßig zu unbemerkten Inkonsistenzen führt. Regelmäßige Testläufe über die GitHub Codeowners Vorschau nehmen dieses Risiko spürbar.

# Quick manual check: does every referenced user still have repo access?
$ grep -oE '@[a-zA-Z0-9_-]+(/[a-zA-Z0-9_-]+)?' CODEOWNERS | sort -u
@mironsoft/backend-team
@mironsoft/frontend-team
@mironsoft/lead-dev
@ex-employee

# Cross-check against current collaborators via GitHub CLI
$ gh api repos/mironsoft/shop/collaborators --jq '.[].login'
mironsoft-lead
frontend-dev-1
backend-dev-2
# @ex-employee is missing here: stale entry, rule silently fails to assign

# GitHub renders a live preview of unmatched or invalid lines
# under Settings > Code owners, always check it before merging changes

9. CODEOWNERS pflegen, wenn sich Teamstruktur und Ownership ändern

Die CODEOWNERS Datei selbst sollte in der eigenen Datei als geschützter Pfad auftauchen, sodass Änderungen daran zwingend von den Tech Leads oder der Teamleitung freigegeben werden müssen, statt dass jede Entwicklerin sich beliebig selbst als Owner eintragen kann. Ein fester Rhythmus, etwa ein kurzer Check pro Quartal im Rahmen eines Team-Retros, deckt verwaiste Einträge zuverlässig auf, bevor sie über Monate unbemerkt Reviews blockieren.

Für größere Organisationen lohnt sich zusätzlich ein automatisiertes Linting in der CI-Pipeline, etwa mit dem Open-Source-Tool codeowners-validator, das prüft, ob alle referenzierten Benutzer und Teams noch existieren, tatsächlich Schreibzugriff besitzen und ob jede Regel mindestens eine Datei im Repository trifft. So werden verwaiste oder wirkungslose Zeilen schon im Pull Request sichtbar, statt erst Monate später bei einem fehlgeschlagenen Review-Versuch aufzufallen.

# .github/workflows/codeowners-lint.yml
name: Lint CODEOWNERS
on:
  pull_request:
    paths:
      - '.github/CODEOWNERS'
      - 'CODEOWNERS'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Fails the build if a referenced user/team no longer exists
      # or has no write access, or a pattern matches zero files
      - name: Validate CODEOWNERS
        uses: mszostok/codeowners-validator@v0.7.4
        with:
          checks: "files,duppatterns,syntax,owners"
          github_access_token: ${{ secrets.GITHUB_TOKEN }}

Die folgende Übersicht zeigt den praktischen Unterschied zwischen einer rein informativen CODEOWNERS Datei und einer Datei, die zusätzlich über Branch Protection tatsächlich durchgesetzt wird.

10. Zusammenfassung

Die CODEOWNERS-Datei löst ein einfaches, aber wichtiges Problem: Sie bindet Wissen über Zuständigkeiten direkt an Dateipfade, statt es implizit im Kopf einzelner Personen zu belassen. GitHub, GitLab und Bitbucket werten die Datei nativ aus und schlagen bei jedem Pull oder Merge Request automatisch die passenden Reviewer vor, basierend auf einer Glob-Syntax, bei der stets das letzte passende Muster gewinnt, nicht das speziellste. Ohne zusätzliche Konfiguration bleibt die Datei jedoch rein informativ und kann jederzeit ignoriert werden.

Erst die Kombination mit Require review from Code Owners auf GitHub beziehungsweise Require approval from code owners auf GitLab macht aus dem Vorschlag eine tatsächliche Voraussetzung für den Merge. Für Magento 2 und Hyvä Projekte lohnt sich eine granulare Aufteilung entlang Frontend, Backend, Datenbankschema und CI/CD-Konfiguration, gepflegt über einen festen Review-Rhythmus und automatisiertes Linting in der Pipeline, damit verwaiste Einträge und stille Syntaxfehler frühzeitig auffallen, statt monatelang unbemerkt Reviews zu blockieren.

11. FAQ: CODEOWNERS-Datei einsetzen