Node.js-Pakete veröffentlichen

Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

Einführung

Dieser Leitfaden zeigt Dir, wie Du einen Workflow erstellen kannst, der Node.js Pakete nach den Tests der fortlaufenden Integration (CI) in die GitHub Packages und npm Registrierungen veröffentlicht.

Voraussetzungen

Wir empfehlen, dass Du ein grundlegendes Verständnis von Workflowkonfigurations-Optionen hast und darüber, wie Du eine Workflow-Datei erstellst. Weitere Informationen findest du unter Informationen zu GitHub Actions.

Weitere Informationen zum Erstellen eines CI-Workflows für dein Node.js-Projekt findest du unter Erstellen und Testen von Node.js-Code.

Vielleicht findest Du es auch hilfreich, ein grundlegendes Verständnis von Folgendem zu haben:

Informationen zur Paketkonfiguration

Die Felder name und version in der package.json-Datei erstellen einen eindeutigen Bezeichner, den Registrierungen zum Verknüpfen deines Pakets mit einer Registrierung verwenden. Du kannst eine Zusammenfassung für die Paketauflistungsseite hinzufügen, indem du ein description-Feld in die package.json-Datei einschließt. Weitere Informationen findest du unter Erstellen einer package.json-Datei und Erstellen von Node.js-Modulen in der npm-Dokumentation.

Wenn eine lokale .npmrc-Datei vorhanden und der registry-Wert angegeben ist, verwendet der npm publish-Befehl die in der .npmrc-Datei konfigurierte Registrierung. Du kannst die setup-node-Aktion verwenden, um auf dem Runner eine lokale NPMRC-Datei zu erstellen, in der die Standardregistrierung und der Standardbereich konfiguriert werden. Die setup-node-Aktion akzeptiert als Eingabe auch ein Authentifizierungstoken, das für den Zugriff auf private Registrierungen oder die Veröffentlichung von Knotenpaketen verwendet wird. Weitere Informationen findest du unter setup-node.

Mithilfe der Aktion setup-node kannst du die im Runner installierte Node.js-Version angeben.

Wenn du in deinem Workflow Schritte zum Konfigurieren der publishConfig-Felder in der package.json-Datei hinzufügst, musst du die Registrierungs-URL (registry-url) nicht mit der setup-node-Aktion angeben. Dann kannst du das Paket jedoch nur in einer einzigen Registrierung veröffentlichen. Weitere Informationen findest du unter publishConfig in der npm-Dokumentation.

Pakete in der npm-Registry veröffentlichen

Du kannst einen Workflow auslösen, um dein Paket jedes Mal zu veröffentlichen, wenn du ein neues Release veröffentlichst. Der Prozess im folgenden Beispiel wird ausgeführt, wenn das Releaseereignis vom Typ published ausgelöst wird. Wenn die CI-Tests erfolgreich sind, lädt der Prozess das Paket in die npm-Registrierung hoch. Weitere Informationen findest du unter Veröffentlichungen in einem Repository verwalten.

Um in deinem Workflow authentifizierte Vorgänge für die npm-Registrierung auszuführen, musst du dein npm-Authentifizierungstoken als Geheimnis speichern. Erstelle beispielsweise ein Repositorygeheimnis namens NPM_TOKEN. Weitere Informationen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

Standardmäßig verwendet npm das name-Feld der package.json-Datei, um den Namen deines veröffentlichten Pakets zu bestimmen. Wenn Du in einem globalen Namespace veröffentlichst, brauchst Du nur den Paketnamen anzugeben. Du kannst beispielsweise ein Paket namens my-package unter https://www.npmjs.com/package/my-package veröffentlichen.

Wenn du ein Paket veröffentlichst, das ein Präfix für den Bereich (scope) enthält, füge den Bereich in den Namen der package.json-Datei ein. Wenn beispielsweise das Präfix des npm-Bereichs „octocat“ und der Paketname „hello-world“ lautet, sollte der name in der package.json-Datei @octocat/hello-world lauten. Wenn dein npm-Paket ein Bereichspräfix verwendet und das Paket öffentlich ist, musst du die Option npm publish --access public verwenden. Dies ist eine Option, die npm verlangt, um zu verhindern, dass jemand versehentlich ein privates Paket veröffentlicht.

In diesem Beispiel wird das NPM_TOKEN-Geheimnis in der Umgebungsvariablen NODE_AUTH_TOKEN gespeichert. Wenn die setup-node-Aktion eine .npmrc-Datei erstellt, verweist sie auf das Token aus derNODE_AUTH_TOKEN-Umgebungsvariablen.

YAML

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Im vorherigen Beispiel erstellt die setup-node-Aktion im Runner eine .npmrc-Datei mit dem folgenden Inhalt:

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
registry=https://registry.npmjs.org/
always-auth=true

Beachte, dass du die registry-url in setup-node auf https://registry.npmjs.org/ festlegen musst, damit deine Anmeldeinformationen ordnungsgemäß konfiguriert werden.

Pakete in der GitHub Packages veröffentlichen

Du kannst einen Workflow auslösen, um dein Paket jedes Mal zu veröffentlichen, wenn du ein neues Release veröffentlichst. Der Prozess im folgenden Beispiel wird ausgeführt, wenn das Releaseereignis vom Typ published ausgelöst wird. Wenn die CI-Tests erfolgreich sind, lädt der Prozess das Paket in GitHub Packages hoch. Weitere Informationen findest du unter Veröffentlichungen in einem Repository verwalten.

Konfigurieren des Zielrepositorys

Die Verknüpfung des Pakets mit GitHub Packages mithilfe des repository-Schlüssels ist optional. Wenn du den repository-Schlüssel in der package.json-Datei nicht bereitstellen möchtest, wird

Wenn du den repository-Schlüssel in deiner package.json-Datei angibst, wird das Repository in diesem Schlüssel als npm-Zielregistrierung für GitHub Packages verwendet. Die Veröffentlichung der folgenden package.json-Ergebnisse führt z. B. zu einem Paket mit dem Namen my-package, das im octocat/my-other-repo GitHub-Repository veröffentlicht wurde. Nach der Veröffentlichung wird nur die Repositoryquelle aktualisiert, und das Paket erbt keine Berechtigungen vom Ziel-Repository.

{
  "name": "@octocat/my-package",
  "repository": {
    "type": "git",
    "url": "https://github.com/octocat/my-other-repo.git"
  },

Authentifizieren beim Zielrepository

Um authentifizierte Vorgänge für die GitHub Packages-Registrierung in deinem Workflow auszuführen, kannst du das GITHUB_TOKEN verwenden. Das GITHUB_TOKEN-Geheimnis wird jedes Mal auf ein Zugriffstoken für das Repository festgelegt, wenn ein Auftrag in einem Workflow beginnt. Die Berechtigungen für dieses Zugriffstoken müssen in der Workflowdatei festgelegt werden, um Lesezugriff auf den contents-Bereich und Schreibzugriff auf den packages-Bereich zu gewähren. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.

Wenn du dein Paket in einem anderen Repository veröffentlichen möchtest, musst du ein personal access token verwenden, das über die Berechtigung zum Schreiben in Pakete im Zielrepository verfügt. Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken und unter Verwenden von Geheimnissen in GitHub-Aktionen.

Beispielworkflow

In diesem Beispiel wird das GITHUB_TOKEN-Geheimnis in der Umgebungsvariablen NODE_AUTH_TOKEN gespeichert. Wenn die setup-node-Aktion eine .npmrc-Datei erstellt, verweist sie auf das Token aus derNODE_AUTH_TOKEN-Umgebungsvariablen.

YAML

name: Publish package to GitHub Packages
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v4
        with:
          node-version: '16.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Publish package to GitHub Packages
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v4
        with:
          node-version: '16.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Die setup-node-Aktion erstellt eine .npmrc-Datei im Runner. Wenn du die scope-Eingabe für die setup-node-Aktion verwendest, enthält die .npmrc-Datei das Bereichspräfix. Die setup-node-Aktion legt den Bereich in der .npmrc-Datei standardmäßig auf das Konto fest, das die Workflowdatei enthält.

//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://npm.pkg.github.com
always-auth=true

Pakete mittels Yarn veröffentlichen

Wenn Du den Paketmanager „Yarn“ verwendest, kannst Du mit Yarn Pakete installieren und veröffentlichen.

YAML

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Um sich während der Veröffentlichung mit der Registrierung zu authentifizieren, muss Ihr Authentifizierungstoken auch in der Datei yarnrc.yml definiert sein. Weitere Informationen finden Sie im Artikel Einstellungen in der Yarn-Dokumentation.

Node.js-Pakete veröffentlichen

In diesem Artikel