Node.js-Pakete veröffentlichen

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. Mit einem einzigen Workflow kannst Du Pakete in einer einzigen Registry oder in mehreren Registries veröffentlichen.

Vorrausetzungen

Wir empfehlen, dass Du ein grundlegendes Verständnis von Workflowkonfigurations-Optionen hast und darüber, wie Du eine Workflow-Datei erstellst. For more information, see "Learn GitHub Actions."

Weitere Informationen zum Erstellen eines CI-Workflows für Dein Node.js-Projekt findest Du unter „Node.js mit GitHub Actions verwenden“.

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

• "Working with the npm registry"
• "Environment variables"
• "Encrypted secrets"
• "Authentication in a workflow"

Informationen zur Paketkonfiguration

Die Felder name und version in der Datei package.json bilden eine eindeutige Kennung. Registries verwenden diese Kennung, um Dein Paket mit einer Registry zu verknüpfen. Du kannst eine Zusammenfassung für die Paketlisten-Seite hinzufügen, indem Du in die Datei package.json ein Feld description einfügst. Weitere Informationen findest Du unter „Eine Datei package.json erstellen“ und „Node.js-Module erstellen“ in der npm-Dokumentation.

Wenn eine lokale Datei .npmrc existiert, in der ein Wert registry angegeben ist, dann verwendet der Befehl npm publish die in der Datei .npmrc konfigurierte Registry. Du kannst die setup-node Aktion verwenden, um eine lokale .npmrc Datei auf dem Läufer zu erstellen, der die Standardregistrierung und -Reichweite konfiguriert. Die setup-node Aktion akzeptiert als Eingabe auch ein Authentifizierungstoken, das für den Zugriff auf private Registrierungen oder das Veröffentlichen von Knotenpaketen verwendet wird. Weitere Informationen findest Du unter setup-node.

Du kannst die auf dem Runner installierte Node.js-Version mit der Aktion setup-node angeben.

Wenn Du Schritte in Deinen Workflow einfügst, um die publishConfig-Felder in Deiner package.json-Datei zu konfigurieren, brauchst Du die Registry-URL nicht mittels der Aktion setup-node anzugeben, aber Du kannst das Paket in nur einer einzigen Registry veröffentlichen. Weitere Informationen finden Sie unter „publishConfig“ in der NPM-Dokumentation.

Pakete in der npm-Registry veröffentlichen

Jedes Mal, wenn Du ein neues Release erstellst, kannst Du einen Workflow anstoßen, um Dein Paket zu veröffentlichen. Der Workflow im folgenden Beispiel wird von dem Ereignis release vom Typ created angestoßen. Der Workflow veröffentlicht das Paket im npm-Registry sofern es die CI-Tests besteht.

To perform authenticated operations against the npm registry in your workflow, you'll need to store your npm authentication token as a secret. For example, create a repository secret called NPM_TOKEN. Weitere Informationen findest Du unter „Verschlüsselte Geheimnisse erstellen und verwenden“.

Standardmäßig verwendet npm das Feld name der Datei package.json, um die npm-Registry zu ermitteln. Wenn Du in einem globalen Namespace veröffentlichst, brauchst Du nur den Paketnamen anzugeben. Zum Beispiel würdest Du ein Paket namens npm-hello-world-test auf https://www.npmjs.com/package/npm-hello-world-test veröffentlichen.

Wenn Du ein Paket veröffentlichst, das einen Präfix für den „scope“ (Geltungsbereich) enthält, dann füge den Geltungsbereich als name in Deine Datei package.json ein. Wenn beispielsweise Dein Präfix für den npm-scope „octocat“ und der Paketname „hello-world“ ist, dann sollte der name in Deiner Datei package.json auf @octocat/hallo-world gesetzt sein. Wenn Dein npm-Paket einen Scope-Prä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.

Dieses Beispiel speichert das Geheimnis NPM_TOKEN in der Umgebungsvariablen NODE_AUTH_TOKEN. Wenn die Aktion setup-node eine Datei .npmrc erzeugt, referenziert sie das Token aus der Umgebungsvariable NODE_AUTH_TOKEN.

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

Im obigen Beispiel erzeugt die Aktion setup-node auf dem Runner eine Datei .npmrc mit folgendem Inhalt:

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

Pakete in der GitHub Packages veröffentlichen

Jedes Mal, wenn Du ein neues Release erstellst, kannst Du einen Workflow anstoßen, um Dein Paket zu veröffentlichen. Der Workflow im folgenden Beispiel läuft jedes Mal, wenn das Ereignis release vom Typ created auftritt. Der Workflow veröffentlicht das Paket in GitHub Packages , wenn die CI-Tests bestanden wurden.

Configuring the destination repository

If you don't provide the repository key in your package.json file, then GitHub Packages publishes a package in the GitHub repository you specify in the name field of the package.json file. For example, a package named @my-org/test is published to the my-org/test GitHub repository.

However, if you do provide the repository key, then the repository in that key is used as the destination npm registry for GitHub Packages. For example, publishing the below package.json results in a package named my-amazing-package published to the octocat/my-other-repo GitHub repository.

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

Authenticating to the destination repository

Um authentifizierte Vorgänge für die Registry GitHub Packages in Deinem Workflow kannst Du den GITHUB_TOKEN verwenden. The GITHUB_TOKEN secret is set to an access token for the repository each time a job in a workflow begins. It has read and write permissions for packages in the repository where the workflow runs. For more information, see "Authenticating with the GITHUB_TOKEN."

If you want to publish your package to a different repository, you must use a personal access token (PAT) that has permission to write to packages in the destination repository. For more information, see "Creating a personal access token" and "Encrypted secrets."

Example workflow

Dieses Beispiel speichert das Geheimnis GITHUB_TOKEN in der Umgebungsvariablen NODE_AUTH_TOKEN. Wenn die Aktion setup-node eine Datei .npmrc erzeugt, referenziert sie das Token aus der Umgebungsvariable NODE_AUTH_TOKEN.

name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest 
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v2
        with:
          node-version: '12.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm install
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Die Aktion setup-node erzeugt eine Datei .npmrc auf dem Runner. Wenn Du für die Aktion setup-node die Eingabe scope verwendest, enthält die Datei .npmrc das Präfix „scope“. Standardmäßig legt die Aktion setup-node den „Scope“ (Geltungsbereich) in der Datei .npmrc auf das Konto fest, das diese Workflow-Datei 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.

name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v2
        with:
          node-version: '12.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Pakete auf npm und in der GitHub Packages veröffentlichen

Du kannst Deine Pakete sowohl in der npm-Registry als auch in GitHub Packages veröffentlichen, indem Du die Aktion setup-node für jede Registry verwendest.

Wenn Du ein Paket in beiden Registries veröffentlichst, musst Du sicherstellen, dass Dein „Scope“-Präfix auf npm mit Deinem Benutzer- oder Organisationsnamen in GitHub übereinstimmt. Um Pakete in einer öffentlichen Registry mit einem „Scope“-Präfix zu veröffentlichen, kannst Du den Befehl npm publish --access public verwenden. Weitere Informationen findest Du unter npm-scope und „Öffentliche Pakete mit „Scope“ (Geltungsbereich) anlegen und veröffentlichen“ in der npm-Dokumentation.

Stelle sicher, dass in Deiner Datei package.json den Geltungsbereich Deines GitHub-Repositorys und der npm-Registry angegeben ist. Wenn Du beispielsweise ein Paket im Repository octocat/npm-hello-world-test auf GitHub und https://www.npmjs.com/package/@octocat/npm-hello-world-test veröffentlichen willst, dann sollte in Deiner Datei package.json der Name "name": "@octocat/npm-hello-world-test" stehen.

Um authentifizierte Vorgänge für die Registry GitHub Packages in Deinem Workflow kannst Du den GITHUB_TOKEN verwenden. The GITHUB_TOKEN secret is set to an access token for the repository each time a job in a workflow begins. It has read and write permissions for packages in the repository where the workflow runs. For more information, see "Authenticating with the GITHUB_TOKEN."

Wenn Du für die Aktion setup-node die Eingabe scope verwendest, erstellt die Aktion eine Datei .npmrc mit dem Präfix „scope“. Standardmäßig legt die Aktion setup-node den Geltungsbereich in der Datei .npmrc auf den Benutzer oder die Organisation fest, der die Workflow-Datei gehört.

Dieser Workflow ruft die Aktion setup-node zweimal auf. Jedes Mal, wenn die Aktion setup-node ausgeführt wird, überschreibt sie die Datei .npmrc. Die Datei .npmrc referenziert den Token, mit dem Du authentifizierte Operationen in der Paket-Registry durchführen kannst, durch die Umgebungsvariable NODE_AUTH_TOKEN. Der Workflow setzt die Umgebungsvariable NODE_AUTH_TOKEN jedes Mal, wenn der Befehl npm publish ausgeführt wird; zuerst mit einem Token zum Veröffentlichen auf npm (NPM_TOKEN) und dann mit einem Token zum Veröffentlichen in der GitHub Packages (GITHUB_TOKEN).

name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest 
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v2
        with:
          node-version: '10.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install
      # Publish to npm
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v2
        with:
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      # Publish to GitHub Packages
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}