actions/labeler: Pull-Requests nach Pfaden und Branchnamen etikettieren
Eine Aktion zum automatischen Kennzeichnen von Pull-Anfragen. Was hat sich in V7 geändert? Intern auf ESM migriert, um die neuesten @actions/*-Paketversionen zu unterstützen.
Auf einen Blick
- Was ist das?
- actions/labeler setzt Labels anhand geänderter Dateipfade oder von Basis- und Kopf-Branch. Die Regeln liegen in .github/labeler.yml, mit vier Glob-Modi, any/all-Logik und zwei Grenzwerten für große Pull-Requests.
- Für wen ist es gedacht?
- actions/labeler passt zu Repositorien mit mehreren Zuständigkeitsbereichen, in denen sich aus Pfad und Branchnamen ableiten lässt, wer sich kümmern soll. Es passt weniger zu Projekten, die Labels aus Titeln, Inhalten oder externen Systemen ableiten wollen, denn das Match-Objekt kennt nur Pfade und Branchnamen.
- Darf ich es kommerziell nutzen?
- Ja. MIT ist eine freizügige Lizenz: Sie dürfen darauf aufbauende Software nutzen, verändern und verkaufen, solange Sie die Urheberrechts- und Lizenzhinweise beibehalten.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 3 Tagen.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich TypeScript, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 14. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Wofür actions/labeler zuständig ist: Labels aus Pfaden und Branchnamen
Ein Repository mit vielen offenen Pull-Requests verliert den Überblick, wenn niemand einsortiert. actions/labeler übernimmt diese Sortierung anhand von Fakten, die in der Anfrage ohnehin liegen: den Pfaden der geänderten Dateien sowie den Namen von Basis- und Kopf-Branch.
Die Regeln liegen in `.github/labeler.yml`. Der Schlüssel ist der Labelname im Repository, der Wert ein Match-Objekt. Ein Label für Dokumentation entsteht dadurch, dass eine Änderung unter docs/ liegt.
Der Nutzen steckt nicht im Etikett selbst, sondern in dem, was daran anschließt. Wer Labels hat, kann Zuständige ansprechen, Prüfschritte auslösen oder Freigaben an Bedingungen knüpfen. Genau deshalb lohnt es sich, die Regeln sauber zu schreiben, statt sie rasch zusammenzusetzen.
Das Match-Objekt in .github/labeler.yml: vier Glob-Modi im Vergleich
Für geänderte Dateien kennt das Match-Objekt vier Varianten, und die Unterschiede sind leicht zu verwechseln. `any-glob-to-any-file` trifft zu, wenn irgendein Glob auf irgendeine geänderte Datei passt. `any-glob-to-all-files` verlangt, dass ein Glob auf alle geänderten Dateien passt.
`all-globs-to-any-file` verlangt, dass alle Globs auf mindestens eine geänderte Datei passen. `all-globs-to-all-files` ist die strengste Form, bei der jeder Glob auf jede geänderte Datei passen muss.
Als Muster dienen Pfad-Globs nach minimatch, für Branches reguläre Ausdrücke. Auf ein Detail weist die README eigens hin: Ein führender Stern gehört in Anführungszeichen, sonst deutet YAML ihn als Alias. Aus `'*'` für Dateien im Wurzelverzeichnis wird sonst ein Fehler beim Einlesen.
any und all: boolesche Logik und Negation mit ! in labeler.yml
Über die beiden Top-Level-Schlüssel `any` und `all` lässt sich die Logik kombinieren. Regeln innerhalb von `any` werden ODER-verknüpft, Optionen innerhalb von `all` sowie die Top-Level-Objekte dagegen UND-verknüpft.
Fehlt der Top-Level-Schlüssel, gilt `any`. Diese beiden Schreibweisen sind laut README gleichwertig: ein Match-Objekt mit `changed-files` unmittelbar unter dem Labelnamen, oder dasselbe Objekt unter `any`. Für bestehende Konfigurationen heißt das, dass das Weglassen des Schlüssels kein anderes Verhalten erzeugt.
Mit `!` lassen sich Globs negieren. Ein Label lässt sich damit auf src/** einschränken und src/docs/* ausnehmen. Ohne Negation bleibt bei gemischten Anfragen oft nur ein sehr grobes Raster übrig.
changed-files-labels-limit und max-files-changed: Schutz vor großen PRs
Zwei Top-Level-Optionen begrenzen die Beschriftung bei umfangreichen Änderungen. `changed-files-labels-limit` setzt eine Höchstzahl neuer Labels aus Dateiregeln. Wird sie überschritten, bleiben in diesem Lauf alle neuen Labels aus Dateiregeln weg, Branch-Labels sind davon nicht betroffen.
`max-files-changed` wirkt anders: Überschreitet die Gesamtzahl geänderter Dateien den Wert, wird die gesamte dateibasierte Beschriftung übersprungen. Vorhandene Labels bleiben erhalten, es wird also nichts abgeräumt.
Eine Regel gilt laut README als Datei-Label, sobald sie eine changed-files-Bedingung enthält, selbst wenn sie über eine Branch-Regel zutrifft. Bei einem Umbau, der das halbe Repository berührt, ist das die Option, die einen Labelsturm verhindert.
pull_request_target, configuration-path und sync-labels: die Eingaben
Der Workflow wird auf das Ereignis `pull_request_target` gesetzt, mit den Rechten `contents: read` und `pull-requests: write`. Die Konfiguration liest die Action standardmäßig aus `.github/labeler.yml`; über die Eingabe `configuration-path` lässt sie sich auf eine andere Datei umstellen, wahlweise im Dateisystem des Runners oder im Repository über die GitHub-API.
Zwei Eingaben verdienen Aufmerksamkeit. `sync-labels` entfernt bei true konfigurierte Labels, die nicht mehr zutreffen, und lässt Labels unberührt, die gar nicht in der Konfiguration stehen. Der Mechanismus arbeitet damit nicht destruktiv.
`pr-number` erlaubt geplante Läufe mit festen Pull-Request-Nummern, statt den Kontext zu verwenden. Das ist der Weg, um eine geänderte Konfiguration nachträglich auf bestehende Anfragen anzuwenden.
new-labels und all-labels: was labeler nach dem Lauf ausgibt
Nach dem Durchlauf stellt die Action zwei Ausgaben bereit. `new-labels` enthält die hinzugefügten Labels als kommagetrennte Liste, `all-labels` alle Labels nach dem Lauf.
Damit lassen sich weitere Schritte an Bedingungen knüpfen, etwa ein Benachrichtigungskanal, der nur bei einem bestimmten Label anspringt. Ohne diese Ausgaben müsste ein Folgeschritt die Labels erneut über die API abfragen.
Bei den Rechten gibt es eine Falle, die gern übersehen wird. Das Hinzufügen bestehender Labels verlangt `pull-requests: write`, das Anlegen neuer Labels verlangt zusätzlich `issues: write`. Fehlt die zweite Berechtigung, schlägt der Lauf genau dann fehl, wenn ein Label zum ersten Mal gebraucht wird.
Von Node 20 auf Node 24: die Brüche in labeler v5, v6 und v7
Die Versionsgeschichte ist von Einschnitten geprägt. Version 5 führte die Branch-Zuordnung ein und gestaltete die Konfigurationsstruktur so um, dass alte Dateien nicht mehr passen. Zugleich wurde ein Fehler in `sync-labels` behoben, und die Eingabe `dot` steht seitdem auf true, womit Pfade mit Punkt wie .github mitgehen.
Version 6 hob die Laufzeit von Node 20 auf Node 24 und verlangt Runner ab v2.327.1. Wer ältere selbst betriebene Runner einsetzt, bleibt an dieser Stelle stehen.
Version 7 wanderte intern auf ESM, um neuere @actions/-Pakete zu unterstützen. Nach Auskunft des README bleiben Eingaben, Ausgaben und Verhalten dabei unverändert. Für bestehende Nutzung heißt das: Der Wechsel auf v7 ist der leichte Teil, der Sprung von v4 auf v5 war der schwere.
MIT bei actions/labeler und die Alternative im eigenen Workflow
Beim Trigger `pull_request_target` gilt eine Einschränkung, die ausdrücklich im README steht: Der erste Pull-Request, der den Labeler einführt, löst den Workflow nicht aus, weil dieser vom Basis-Branch ausgeführt wird. Ein Versionswechsel kann ebenfalls scheitern, wenn dort noch eine alte Konfiguration liegt.
Als Alternative zur Action lässt sich die Beschriftung mit `gh`-Befehlen im eigenen Workflow erledigen. Der Unterschied liegt im Regelwerk: Eine eigene Lösung muss Glob-Logik, Grenzwerte und das Entfernen nicht mehr passender Labels selbst bauen, gewinnt dafür die Freiheit, Labels aus beliebigen Quellen abzuleiten.
Wer zwei oder drei Regeln braucht, kommt damit aus. Wer ein Regelwerk über Monate pflegt, nimmt besser die unter MIT stehende Action, deren Glob-Verhalten bereits durch Tests abgedeckt ist.
Redaktionelles Fazit
actions/labeler passt zu Repositorien mit mehreren Zuständigkeitsbereichen, in denen sich aus Pfad und Branchnamen ableiten lässt, wer sich kümmern soll. Es passt weniger zu Projekten, die Labels aus Titeln, Inhalten oder externen Systemen ableiten wollen, denn das Match-Objekt kennt nur Pfade und Branchnamen. Der erste Schritt ist kein Umbau, sondern ein Kontrolllauf: `.github/labeler.yml` mit einer einzigen Regel anlegen, den Workflow auf pull_request_target setzen und mit `sync-labels: false` starten, damit ein fehlerhaftes Muster keine bestehenden Labels entfernt.
Community-Notizen