npm Trusted Publishing mit GitHub Actions: Pakete ohne NPM_TOKEN veröffentlichen

Diese Anleitung erklärt, wie npm-Pakete mit npm Trusted Publishing, OpenID Connect (OIDC) und npm Provenance aus GitHub Actions veröffentlicht werden, ohne ein langfristiges NPM_TOKEN in GitHub Secrets zu speichern.

Wenn du npm publish E404 Not Found, Access token expired or revoked, abgelaufene npm Tokens, fehlgeschlagene GitHub-Actions-Releases, 404-Fehler bei scoped Packages oder das Verhalten von npm publish --access public untersuchst, nutze die folgende Konfiguration und Checkliste.

Kernaussage

Für npm-Publishing aus GitHub Actions ist npm Trusted Publishing besser geeignet als ein langfristiges NPM_TOKEN.

Eine korrekte Einrichtung braucht vier Dinge:

Einen Trusted Publisher in den npm-Paketeinstellungen mit exakter GitHub Organization oder User, Repository und Workflow-Dateiname.
Einen GitHub-hosted Runner. Self-hosted Runner werden von npm Trusted Publishing nicht unterstützt.
permissions: id-token: write, damit GitHub Actions ein OIDC-Identity-Token ausstellen kann.
Eine aktuelle Node/npm-Toolchain mit Unterstützung für OIDC Publishing. Node 24 plus npm latest ist eine praktische Basis.

Dieser Artikel basiert auf der realen Migration von n2n-memory von tokenbasiertem Publishing zu Trusted Publishing. Die technische Konfiguration wurde verifiziert.

Wann diese Anleitung passt

Diese Anleitung ist relevant, wenn du suchst nach:

npm Trusted Publishing konfigurieren
npm-Paket aus GitHub Actions veröffentlichen
npm package ohne NPM_TOKEN veröffentlichen
npm OIDC publishing einrichten
npm publish E404 Not Found - PUT beheben
Access token expired or revoked beheben
Warum GitHub Actions nach Ablauf eines npm Tokens fehlschlägt
npm provenance aktivieren
Warum scoped package publishing 404 zurückgibt
Wann npm publish --access public nötig ist

Warum NPM_TOKEN durch Trusted Publishing ersetzen

Der klassische Ablauf speichert NPM_TOKEN in GitHub Secrets, setzt NODE_AUTH_TOKEN in CI und führt npm publish aus. Das funktioniert, hat aber operative und sicherheitstechnische Nachteile:

Tokens laufen ab, werden widerrufen oder müssen manuell rotiert werden.
Ein geleakter Token ist schwer sauber einzugrenzen.
Mit 2FA sind oft Bypass- oder Automation-Token-Regeln nötig.
Bei mehreren Repositories und Paketen wird Secret-Verwaltung schnell unübersichtlich.

Trusted Publishing funktioniert anders. npm vertraut einem bestimmten Workflow in einem bestimmten GitHub Repository. Wenn dieser Workflow npm publish ausführt, stellt GitHub Actions kurzlebige OIDC-Credentials bereit. npm prüft die Workflow-Identität, erlaubt die Veröffentlichung und kann Provenance-Metadaten erzeugen.

Kurz gesagt: Trusted Publishing lässt npm dem veröffentlichenden GitHub Workflow vertrauen, nicht einem langfristigen Token.

npm einrichten: Trusted Publisher hinzufügen

Öffne die Access-Seite des Pakets:

https://www.npmjs.com/package/<package-name>/access

Zum Beispiel:

https://www.npmjs.com/package/n2n-memory/access

Gehe zu Settings, suche Trusted Publishers, wähle GitHub Actions und fülle aus:

Feld	Wert
Organization or user	`n2ns`, das GitHub-Konto oder die Organization
Repository	`n2n-memory`, der Repository-Name
Workflow filename	`publish.yml`, nur der Dateiname
Environment name	Leer lassen, außer du nutzt ein GitHub Environment

Wichtige Details:

Workflow filename ist nur der Dateiname, zum Beispiel publish.yml.
Nicht den vollständigen Pfad .github/workflows/publish.yml eintragen.
Organization or user, Repository und Workflow filename müssen exakt mit GitHub übereinstimmen.
Die Felder sind case-sensitive.
Nach dem Bearbeiten Save changes klicken, sonst wird die Konfiguration nicht übernommen.

Empfohlener GitHub Actions Workflow

Diese .github/workflows/publish.yml ist eine verifizierte Basis:

name: Publish Package

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

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

      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'

      - name: Upgrade npm
        run: npm install -g npm@latest

      - run: npm ci

      - run: npm run check

      - run: npm publish --access public

Wichtige Punkte:

permissions: id-token: write ist für OIDC Publishing erforderlich.
runs-on: ubuntu-latest nutzt einen GitHub-hosted Runner. npm Trusted Publishing unterstützt keine self-hosted Runner.
node-version: '24' vermeidet unvollständige Unterstützung in älteren npm-CLI-Versionen.
npm install -g npm@latest stellt eine aktuelle npm CLI sicher.
registry-url sollte explizit https://registry.npmjs.org sein.
Öffentliche scoped Packages sollten Folgendes verwenden:

npm publish --access public

Setze kein NODE_AUTH_TOKEN für npm publish, sonst kann npm den alten Token-Pfad statt OIDC Trusted Publishing nutzen.

Empfohlene package.json-Konfiguration

Nutze die echte Repository-URL und öffentliche Publishing-Konfiguration:

{
  "name": "n2n-memory",
  "version": "1.2.2",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/n2ns/n2n-memory.git"
  },
  "publishConfig": {
    "access": "public",
    "provenance": true
  }
}

Hinweise:

repository.url sollte auf das echte GitHub Repository zeigen.
npm provenance prüft die Publishing-Quelle. Eine falsche Repository-URL kann Fehler oder inkonsistente Metadaten verursachen.
Öffentliche scoped Packages sollten publishConfig.access: "public" behalten.
publishConfig.provenance: true aktiviert npm provenance explizit.

Vollständiger Release-Ablauf

Nach der Konfiguration:

Trusted Publisher in npm hinzufügen und speichern.
.github/workflows/publish.yml committen und pushen:

git add .github/workflows/publish.yml package.json
git commit -m "chore: configure npm trusted publishing"
git push

Sicherstellen, dass die package.json-Version noch nicht veröffentlicht wurde.
Tag erstellen und pushen:

git tag v1.2.2
git push origin v1.2.2

Den Publish Package Job in GitHub Actions abwarten.
Die npm-Veröffentlichung prüfen:

npm view n2n-memory dist-tags.latest
npm view n2n-memory versions --json

Wenn dist-tags.latest auf die neue Version zeigt, war die Veröffentlichung erfolgreich.

Fehlerbehebung

Warum gibt npm publish E404 Not Found zurück?

Ein typischer Fehler sieht so aus:

npm error code E404
npm error 404 Not Found - PUT https://registry.npmjs.org/@scope%2fpackage - Not found
npm error 404 '@scope/[email protected]' is not in this registry.

Bei npm publish bedeutet das oft, dass die Publishing-Berechtigung fehlt oder die Trusted-Publisher-Identität nicht passt. Prüfe der Reihe nach:

Trusted Publisher wurde mit Save changes gespeichert
Organization or user entspricht exakt dem GitHub Owner
Repository entspricht exakt dem Repository-Namen
Workflow filename ist nur publish.yml, ohne Pfad
Die Workflow-Datei liegt wirklich unter .github/workflows/publish.yml
Der Workflow nutzt einen GitHub-hosted Runner
Der Workflow enthält permissions: id-token: write
Node ist 24 und npm wurde auf latest aktualisiert
Das öffentliche scoped Package nutzt npm publish --access public

Wie behebt man Access token expired or revoked?

Wenn nach der Migration zu Trusted Publishing weiterhin Folgendes erscheint:

Access token expired or revoked

nutzt npm CLI vermutlich noch den alten Token-Authentifizierungspfad. Prüfe:

Entferne NODE_AUTH_TOKEN aus dem npm publish Schritt.
Entferne tokenbasierte .npmrc-Schreibvorgänge aus dem Workflow.
Aktualisiere Node/npm.
Verwende keine alten Publish-Actions oder Skripte, die Token injizieren.

Bei korrekt konfiguriertem Trusted Publishing braucht der Release-Workflow kein NPM_TOKEN.

Warum validiert npm whoami OIDC nicht?

npm whoami nutzt klassische Authentifizierung. Es beweist nicht, dass Trusted Publishing OIDC korrekt eingerichtet ist.

Die verlässliche Validierung ist, den Publish-Workflow auszuführen und zu prüfen, ob npm publish erfolgreich ist.

Warum kann workflow_dispatch fehlschlagen?

npm prüft die Identität des Workflows, der tatsächlich veröffentlicht. Lasse npm publish in demselben publish.yml, das als Trusted Publisher registriert ist. Vermeide verschachtelte oder reusable Workflows, außer du hast geprüft, dass die registrierte Workflow-Identität weiterhin passt.

Warum kann Publishing nach einem Owner-Transfer scheitern?

Die Übertragung eines npm-Paket-Owners aktualisiert Trusted Publisher nicht automatisch. Nach einem Transfer prüfen:

Das aktuelle npm-Konto hat Schreibzugriff auf das Paket.
Trusted Publisher zeigt auf den aktuellen GitHub Owner und das Repository.
Der Workflow-Dateiname stimmt mit npm überein.
package.json enthält die aktuelle repository.url.

Minimale Checkliste

Vor dem Publishing prüfen:

npm Paket hat einen gespeicherten Trusted Publisher
Workflow filename ist publish.yml, nur Dateiname
Workflow-Pfad ist .github/workflows/publish.yml
Workflow enthält permissions: id-token: write
Workflow nutzt einen GitHub-hosted Runner wie ubuntu-latest
Workflow nutzt node-version: '24'
Workflow führt npm install -g npm@latest aus
npm publish nutzt kein NODE_AUTH_TOKEN
package.json repository.url zeigt auf das aktuelle GitHub Repository
package.json enthält publishConfig.access: "public"
Die Paketversion wurde noch nicht veröffentlicht

FAQ

Braucht npm Trusted Publishing noch NPM_TOKEN?

Nein. Trusted Publishing nutzt kurzlebige GitHub-Actions-OIDC-Identität statt eines langfristigen NPM_TOKEN.

Unterstützt npm Trusted Publishing self-hosted Runner?

Nein. Der Publishing-Workflow muss einen GitHub-hosted Runner wie ubuntu-latest verwenden.

Was gehört in Workflow filename?

Nur der Dateiname, zum Beispiel publish.yml. Nicht .github/workflows/publish.yml.

Warum --access public für scoped Packages?

Öffentliche scoped Packages können sonst als privat behandelt werden. Nutze:

npm publish --access public

Und behalte dies in package.json:

"publishConfig": {
  "access": "public",
  "provenance": true
}

Sind Trusted Publishing und provenance dasselbe?

Nein. Trusted Publishing validiert über GitHub Actions OIDC, wer veröffentlicht. Provenance dokumentiert, woher das Paket stammt. Beide Funktionen ergänzen sich.