Alles, woran ich beim Veröffentlichen von @hsblabs/web-stream-extras auf npm gescheitert bin

Als npm publish durchlief, war das ein gutes Gefühl.

Die Probleme kamen danach. Sobald ich zu GitHub Actions wechselte, brachen drei Dinge. Die Trusted-Publisher-Konfiguration, Metadaten rund um provenance und die Reihenfolge von Tags und Versionen—jedes scheiterte aus einem anderen Grund, an einer anderen Stelle.

Ich schreibe das hier auf, damit die nächste Person nicht dieselbe Zeit verliert.

Warum ich das Paket veröffentlichen wollte

@hsblabs/web-stream-extras ist ein kleines Paket mit Hilfsfunktionen rund um die Web Streams API. Ursprünglich für die interne Wiederverwendung geschrieben, entschied ich mich, es als OSS zu veröffentlichen, da es allgemein genug ist.

Warum ich 0.0.1 manuell vom lokalen Rechner veröffentlichte

Beim ersten Release führte ich npm publish lokal aus, bevor ich Actions einrichtete. Ziel war es zu prüfen, ob Install und Import tatsächlich funktionieren, sobald das Paket auf npm liegt. Die Release-Infrastruktur überließ ich für später—Automatisierung einzurichten bevor alles stabil ist, fügt nur eine weitere Debugging-Schicht hinzu.

Es gibt noch einen weiteren Grund. Um Trusted Publisher auf der npmjs-Seite zu konfigurieren, muss das Paket bereits auf npm existieren. Das heißt, die erste Veröffentlichung muss irgendwie manuell erfolgen. Ohne das kommt man gar nicht erst zur Einstellungsseite.

Umstieg auf GitHub Actions + Trusted Publisher für 0.1.0

Die manuelle Veröffentlichung blieb einmalig, danach lief alles über GitHub Actions.

npm’s Trusted Publisher ermöglicht die Veröffentlichung per OIDC ohne Token-Verwaltung. Er nutzt einen kurzlebigen Token des Workflows, sodass kein NPM_TOKEN als Secret gespeichert werden muss.

Zwei Dinge sind für die Konfiguration entscheidend. Auf der npm-Seite gibt man beim Hinzufügen eines Trusted Publishers den Workflow-Dateinamen an. Auf der GitHub-Actions-Seite fügt man die Berechtigung id-token: write hinzu und lässt NODE_AUTH_TOKEN weg.

permissions:
  id-token: write
  contents: read

Wird NODE_AUTH_TOKEN stehen gelassen, kann der OIDC-Flow des Trusted Publishers fehlschlagen. Token-basierte Anleitungen, die noch in README oder TODO stehen, sorgen für Verwirrung—bei der Migration am besten alles bereinigen.

Tatsächlich aufgetretene Fehler

Publish stoppt mit 422 Unprocessable Entity

Nur der Publish-Step in Actions schlug fehl. Der Fehler war 422 Unprocessable Entity. Alle anderen Steps liefen durch, sodass ich zunächst keine Ahnung hatte, wo ich suchen sollte.

Die Ursache war ein leeres repository.url in package.json. Wenn provenance aktiviert ist, nutzt npm repository.url, um das Paket mit dem Repository zu verknüpfen. Fehlt das Feld, kommt ein 422.

// vorher
"repository": {}

// nachher
"repository": {
  "type": "git",
  "url": "https://github.com/hsblabs/web-stream-extras"
}

Auch wenn man alle anderen Metadaten geprüft hat, übersieht man dieses Feld leicht.

Reihenfolge von Tag und package.json.version

Der Workflow prüft, ob der Tag-Name mit package.json.version übereinstimmt.

Wenn man den Tag setzt, bevor die Version erhöht wird, schlägt die Prüfung fehl. Die korrekte Reihenfolge:

1. package.json.version erhöhen und committen
2. Diesen Commit taggen
3. Pushen

Ist die Reihenfolge umgekehrt, stimmt die Version im Commit, auf den der Tag zeigt, nicht mit dem Tag-Namen überein. Bei einem Fehler muss der Tag gelöscht und neu gesetzt werden.

git tag -d v0.1.0
git push origin :refs/tags/v0.1.0
# nach dem Commit mit der Version-Erhöhung
git tag v0.1.0
git push origin v0.1.0

Der schließlich stabile Release-Flow

So funktioniert es jetzt:

1. Implementieren und testen
2. package.json.version erhöhen und committen
3. Einen v{version}-Tag pushen
4. Actions erkennt den Tag-Push und führt die Veröffentlichung aus

Die Pre-Publish-Validierung ist im Befehl publish:check zusammengefasst—Lint und Typprüfungen ohne --write. Diesen Schritt vor dem Publish einzufügen verhindert, dass ungespeicherte Änderungen hineinrutschen. Das direkte Verknüpfen automatisch korrigierender Befehle kann kurz vor dem Publish ungespeicherte Änderungen erzeugen—das sollte man im Hinterkopf behalten.

Mit pnpm pack --dry-run überprüfte ich auch den Inhalt des Tarballs. Selbst wenn files nur auf dist/ zeigt, können Sourcemaps trotzdem enthalten sein. Wer sie nicht veröffentlichen will, sollte sie besser auf der Build-Seite ausschließen.

Was ich als nächstes verbessern will

Die automatische Changelog-Generierung möchte ich in den Flow integrieren. Derzeit ist es manuell, und bei jedem Tag-Push geht etwas unter.

Die Schritte für den Wechsel von manueller Veröffentlichung zu Actions sind unkompliziert. Die Tücken liegen in den Konfigurationsdetails. Trusted Publisher nimmt einem die Token-Verwaltung ab, erfordert aber präzise abgestimmte OIDC-Einstellungen. Am schnellsten kommt man voran, wenn man erst prüft, dass npm-Seite und Actions-Seite eins zu eins übereinstimmen.