Release-Workflows leicht gemacht mit Changesets

Das Veröffentlichen von npm-Paketen sollte keine benutzerdefinierten Skripte, manuellen Versionsaktualisierungen oder das Erinnern erfordern, welche Pakete sich seit Ihrer letzten Veröffentlichung geändert haben. Dennoch basteln viele Teams immer noch fragile Release-Prozesse zusammen, die zum ungünstigsten Zeitpunkt versagen.

Changesets löst dies, indem es die Release-Absicht zum Zeitpunkt des Beitrags erfasst und dann den Rest automatisiert. Dieser Artikel behandelt, wie Sie einen modernen Changesets-Release-Workflow aufbauen – einschließlich npm Trusted Publishing, Monorepo-Versionierung mit Changesets und GitHub Actions Package Releases – ohne die Wartungslast.

Der grundlegende Changesets-Release-Workflow

Der Workflow folgt drei Phasen:

1. Mitwirkende fügen Changeset-Dateien hinzu, die beschreiben, was sich geändert hat und wie bedeutend es ist (patch, minor, major)
2. CI erstellt einen Versionierungs-PR, der alle Changesets zu Versionserhöhungen und Changelog-Einträgen aggregiert
3. Das Mergen des PR löst die Veröffentlichung auf npm mit ordnungsgemäßer Herkunftsnachweisführung aus

Jedes Changeset ist eine Markdown-Datei in .changeset/, die Frontmatter enthält, das betroffene Pakete und den Semver-Bump-Typ spezifiziert, plus eine menschenlesbare Zusammenfassung. Wenn mehrere Changesets existieren, berechnet Changesets die höchste notwendige Versionserhöhung pro Paket – zwei Minor-Änderungen werden nicht zu zwei Minor-Bumps.

Für Monorepos ist dies von erheblicher Bedeutung. Changesets behandelt automatisch interne Abhängigkeitsaktualisierungen, wenn ein Workspace-Paket von einem anderen abhängt, das veröffentlicht wird.

GitHub Actions Package Releases: Der moderne Ansatz

Die meisten Tutorials zeigen Workflows mit NPM_TOKEN-Secrets. Dieser Ansatz funktioniert, birgt aber Sicherheitsrisiken – langlebige Tokens können leaken und erfordern manuelle Rotation.

npm Trusted Publishing mit OIDC-Tokens ist jetzt die bevorzugte Methode. Anstatt Credentials zu speichern, fordert Ihr GitHub Actions Workflow während des Publish-Schritts direkt von npm einen kurzlebigen Token an. Der Token existiert nur für diesen Job und kann nicht extrahiert oder wiederverwendet werden.

Um dies zu aktivieren:

1. Verknüpfen Sie Ihr npm-Paket mit Ihrem GitHub-Repository in den npm-Paketeinstellungen
2. Konfigurieren Sie Ihren Workflow mit der Berechtigung id-token: write
3. Stellen Sie sicher, dass Provenance aktiviert ist (npm kann es automatisch für vertrauenswürdige Publisher generieren oder über das Flag --provenance bei neueren CLIs)

npm Provenance fügt eine kryptografische Attestierung hinzu, die beweist, dass das Paket aus einem bestimmten Commit in Ihrem Repository erstellt wurde. Benutzer können genau verifizieren, welcher Quellcode das veröffentlichte Artefakt produziert hat.

Aktuelle Einschränkungen, die Sie kennen sollten: npm Trusted Publishing erfordert öffentliche Repositories. Private Repos benötigen weiterhin den Legacy-Ansatz mit NPM_TOKEN. Zusätzlich hat die offizielle changesets/action eine sich entwickelnde Unterstützung für OIDC – prüfen Sie die aktuelle Dokumentation für die neuesten Integrationsmuster.

Monorepo-Versionierung mit Changesets

Changesets wurde von Anfang an für Monorepos entwickelt. Wichtige Konfigurationsoptionen in .changeset/config.json steuern das Multi-Paket-Verhalten:

• linked: Gruppiert Pakete, die immer die gleiche Versionsnummer teilen sollen
• fixed: Ähnlich wie linked, aber alle Pakete werden zusammen erhöht, auch wenn sich nur eines geändert hat
• updateInternalDependencies: Steuert, ob abhängige Pakete Patch-Bumps erhalten, wenn ihre Abhängigkeiten aktualisiert werden

Wenn ein Mitwirkender die Changeset-CLI in einem Monorepo ausführt, wählt er aus, welche Pakete seine Änderung betrifft. Der Versionierungs-PR zeigt dann genau, welche Pakete in welchen Versionen veröffentlicht werden.

Häufige CI-Fallstricke

Berechtigungsprobleme verursachen die meisten Workflow-Fehler. Das GitHub-Token benötigt Schreibzugriff zum Erstellen von PRs und Pushen von Tags. Für npm-Publishing stellen Sie sicher, dass Ihr Token (oder Ihre OIDC-Konfiguration) Veröffentlichungsrechte für alle Pakete in Ihrem Scope hat.

PR-Automatisierungskonflikte treten auf, wenn Branch-Protection-Regeln den Bot daran hindern, Versions-Commits zu pushen. Erlauben Sie entweder dem GitHub Actions Bot, den Schutz zu umgehen, oder verwenden Sie ein dediziertes Bot-Konto mit entsprechenden Berechtigungen.

Multi-Paket-Veröffentlichungsreihenfolge ist wichtig, wenn Pakete voneinander abhängen. Changesets behandelt dies automatisch, aber Netzwerkfehler während der Veröffentlichung können Ihr Monorepo in einem inkonsistenten Zustand hinterlassen. Die changesets/action enthält Retry-Logik, aber das Verständnis dieses Fehlermodus hilft bei der Wiederherstellung.

Vergessene Changesets sind der häufigste Fehler von Mitwirkenden. Der Changeset-Bot kommentiert PRs, denen Changesets fehlen, aber Sie können auch CI-Checks hinzufügen, die fehlschlagen, wenn Changesets erforderlich, aber nicht vorhanden sind.

Strukturierung Ihres Workflows heute

Die meisten Teams führen die Changesets-Action bei jedem Push zu main aus. Die Action öffnet oder aktualisiert entweder einen “Version Packages”-PR, wenn unveröffentlichte Changesets existieren, oder veröffentlicht Pakete, wenn der Versions-PR gemergt wird.

Dies schafft einen natürlichen Release-Rhythmus: Mergen Sie Features während der Woche und mergen Sie dann den Versions-PR, wenn Sie bereit zum Ausliefern sind. Keine manuelle Versionsbearbeitung, kein Vergessen von Changelog-Updates, keine Veröffentlichung falscher Pakete.

Fazit

Ein gut konfigurierter Changesets-Release-Workflow entfernt den kognitiven Overhead von Paketveröffentlichungen. Mitwirkende deklarieren die Absicht im Voraus, CI übernimmt die Koordination, und npm Trusted Publishing gewährleistet sichere, verifizierbare Artefakte.

Beginnen Sie mit einem Single-Package-Setup, um den Ablauf zu verstehen, und erweitern Sie dann bei Bedarf auf Monorepos. Die anfängliche Konfigurationsinvestition zahlt sich schnell in reduzierter Release-Angst und weniger “Hoppla, falsche Version”-Momenten aus.

FAQs

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.