Arbeiten mit der npm-Registrierung

URL für die npm registry

Wenn du auf GitHub unter GitHub.com zugreifst, veröffentlichst du Pakete in https://npm.pkg.github.com. In den Beispielen in diesem Artikel wird diese URL verwendet.

Wenn du auf GitHub in einer anderen Domäne zugreifst, z. B. octocorp.ghe.com, ersetzt du „https://npm.pkg.github.com“ durch https://npm.SUBDOMAIN.ghe.com, wobei SUBDOMAIN die eindeutige Unterdomäne deines Unternehmens ist.

Bei GitHub Packages authentifizieren

Du benötigst ein Zugriffstoken, um private, interne und öffentliche Pakete zu veröffentlichen, zu installieren und zu löschen.

Du kannst ein personal access token (classic) für die Authentifizierung bei GitHub Packages oder bei der GitHub-API verwenden. Wenn du ein personal access token (classic) erstellst, kannst du dem Token je nach Bedarf verschiedene Bereiche zuweisen. Weitere Informationen zu paketbezogenen Bereichen für ein personal access token (classic) findest du unter Informationen zu Berechtigungen für GitHub-Pakete.

Um dich bei einer GitHub Packages-Registrierung innerhalb eines GitHub Actions-Workflows zu authentifizieren, kannst du Folgendes verwenden:

• GITHUB_TOKEN, um Pakete zu veröffentlichen, die mit dem Workflowrepository verbunden sind.
• Ein personal access token (classic) (diesem muss mindestens der Bereich read:packages zugeordnet sein), um Pakete zu installieren, die zu anderen privaten Repositorys gehören (auf die GITHUB_TOKEN nicht zugreifen kann)

Authentifizieren in einem GitHub Actions-Workflow

Diese Registrierung unterstützt präzise Berechtigungen. Wenn dein GitHub Actions-Workflow ein personal access token zum Authentifizieren bei einer Registrierung verwendet, solltest du für Registrierungen, die differenzierte Berechtigungen unterstützen, deinen Workflow unbedingt so aktualisieren, dass das GITHUB_TOKEN verwendet wird. Eine Anleitung zum Aktualisieren deiner Workflows, die sich mit einem personal access token bei einer Registrierung authentifizieren, findest du unter Veröffentlichen und Installieren eines Pakets mit GitHub Actions.

Sie können ein GITHUB_TOKEN in einem GitHub Actions-Workflow verwenden, um ein Paket mithilfe der REST-API zu löschen oder wiederherzustellen, wenn das Token über die admin-Berechtigung für das Paket verfügt. Repositorys, die Pakete mithilfe eines Workflows veröffentlichen, und Repositorys, die du explizit mit Paketen verbunden hast, erhalten automatisch die admin-Berechtigung für Pakete im Repository.

Weitere Informationen zum GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu den Best Practices bei der Verwendung einer Registrierung in Actions findest du unter Sicherheitshärtung für GitHub Actions.

Du kannst außerdem auswählen, ob du Zugriffsberechtigungen auf Pakete unabhängig voneinander für GitHub Codespaces und GitHub Actions erteilen möchtest. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen und unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.

Authentifizieren mit einem personal access token

Du musst ein personal access token (classic) mit den entsprechenden Bereichen verwenden, um Pakete in GitHub Packages zu veröffentlichen und zu installieren. Weitere Informationen findest du unter Einführung in GitHub-Pakete.

Du kannst dich bei GitHub Packages mit npm authentifizieren, indem du entweder die benutzerspezifische Datei ~/.npmrc so bearbeitest, dass dein personal access token (classic) enthalten ist, oder indem du dich über die Befehlszeile mit deinem Benutzernamen und deinem personal access token bei npm anmeldest.

Wenn du dich authentifizieren möchtest, indem du dein personal access token (classic) zu deiner ~/.npmrc-Datei hinzufügst, bearbeite die ~/.npmrc-Datei für dein Projekt so, dass sie die folgende Zeile enthält. Ersetze dabei TOKEN durch dein personal access token. Erstelle eine neue Datei ~/.npmrc, wenn keine solche Datei vorhanden ist.

//npm.pkg.github.com/:_authToken=TOKEN

Wenn du dich bei der Anmeldung bei npm authentifizieren möchtest, verwende den Befehl npm login, ersetze USERNAME durch deinen GitHub-Benutzernamen, TOKEN durch dein personal access token (classic) und PUBLIC-EMAIL-ADDRESS durch deine E-Mail-Adresse.

Wenn du die npm CLI Version 9 oder höher verwendest und du dich über die Befehlszeile bei einer privaten Registrierung anmeldest oder von dieser abmeldest, solltest du die --auth-type=legacy-Option verwenden, um deine Authentifizierungsdetails aus Eingabeaufforderungen einlesen zu können, anstatt den Standardanmeldeflow über einen Browser zu verwenden. Weitere Informationen finden Sie unter npm-login.

Wenn GitHub Packages nicht deine Standardpaketregistrierung für die Verwendung von npm ist und du den npm audit-Befehl verwenden möchtest, empfiehlt es sich, das --scope-Flag mit dem Namespace zu verwenden, der das Paket hostet (das persönliche Konto oder die Organisation, auf die das Paket beschränkt ist), wenn du dich bei GitHub Packages authentifizierst.

$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN

Veröffentlichen eines Pakets

• Für Paketnamen und Bereiche dürfen nur Kleinbuchstaben verwendet werden.
• Der Tarball für eine npm-Version muss kleiner als 256 MB sein.

Die GitHub Packages-Registrierung speichert npm-Pakete in deiner Organisation oder deinem persönlichen Konto und ermöglicht es dir, ein Paket einem Repository zuzuordnen. Du kannst wählen, ob Berechtigungen von einem Repository geerbt oder präzise Berechtigungen unabhängig von einem Repository festgelegt werden sollen.

Wenn du ein Paket zum ersten Mal veröffentlichst, ist die Sichtbarkeit standardmäßig auf privat eingestellt. Informationen zum Ändern der Sichtbarkeit oder zum Festlegen von Zugriffsberechtigungen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen. Weitere Informationen zum Verknüpfen eines veröffentlichten Pakets mit einem Repository findest du unter Verbinden eines Repositorys mit einem Paket.

Sie können ein Paket mit einem Repository verbinden, sobald das Paket veröffentlicht wird, indem Sie ein repository-Feld in die package.json-Datei einschließen. Sie können diese Methode auch verwenden, um mehrere Pakete mit demselben Repository zu verbinden. Weitere Informationen findest du unter Veröffentlichen mehrerer Pakete im selben Repository.

Du kannst die Bereichszuordnung für dein Projekt entweder mithilfe einer lokalen .npmrc-Datei im Projekt oder mithilfe der publishConfig-Option in der Datei package.json einrichten. GitHub Packages unterstützt nur bereichsbezogene npm-Pakete. Die Namen bereichsbezogener Pakete weisen das Format @NAMESPACE/PACKAGE-NAME auf. Bereichsbezogene Pakete beginnen immer mit dem Symbol @. Möglicherweise musst du den Namen in der Datei package.json aktualisieren, um den bereichsbezogenen Namen zu verwenden. Wenn du beispielsweise der Benutzer octocat bist und dein Paket den Namen test hat, weise den bereichsbezogenen Paketnamen wie folgt zu: "name": "@octocat/test".

Nachdem Du ein Paket veröffentlicht hast, kannst Du das Paket auf GitHub ansehen. Weitere Informationen findest du unter Pakete anzeigen.

Veröffentlichen eines Pakets mit einer lokalen .npmrc-Datei

Du kannst eine .npmrc-Datei verwenden, um die Bereichszuordnung für dein Projekt zu konfigurieren. Verwende in der Datei .npmrc die GitHub Packages-URL und den Kontobesitzer, damit GitHub Packages weiß, wohin Paketanforderungen weitergeleitet werden sollen. Durch die Verwendung einer .npmrc-Datei wird verhindert, dass andere Entwickler*innen das Paket versehentlich auf npmjs.org anstatt auf GitHub Packages veröffentlichen.

1. Authentifizieren bei GitHub Packages. Weitere Informationen findest Du unter Authentifizieren bei GitHub Packages.

2. Erstelle oder bearbeite eine .npmrc-Datei in demselben Verzeichnis wie deine package.json-Datei, um eine Zeile einzuschließen, die die GitHub Packages-URL und den Namespace angibt, in dem das Paket gehostet wird. Ersetze NAMESPACE durch den Namen des Benutzer- oder Organisationskontos , auf das das Paket ausgerichtet wird.

   @NAMESPACE:registry=https://npm.pkg.github.com
   

3. Füge die NPMRC-Datei dem Repository hinzu, in dem GitHub Packages dein Projekt finden kann. Weitere Informationen findest du unter Eine Datei zu einem Repository hinzufügen.

4. Überprüfe den Namen deines Pakets in der Datei package.json deines Projekts. Das Feld name muss den Bereich und den Namen des Pakets enthalten. Wenn dein Paket beispielsweise den Namen „test“ trägt und du es in der GitHub-Organisation „My-org“ veröffentlichen möchtest, muss das Feld name in der Datei package.json @my-org/test lauten.

5. Überprüfe das Feld repository in der Datei package.json deines Projekts. Das Feld repository muss mit der URL für Ihr GitHub-Repository übereinstimmen. Wenn ihre Repository-URL beispielsweise github.com/my-org/test lautet, sollte das Repositoryfeld https://github.com/my-org/test.git lauten.

6. Das Paket veröffentlichen:

   npm publish
   

Veröffentlichen eines Pakets mithilfe von publishConfig in der Datei package.json

Du kannst das publishConfig-Element in der Datei package.json verwenden, um die Registrierung anzugeben, in der das Paket veröffentlicht werden soll. Weitere Informationen findest du unter publishConfig in der npm-Dokumentation.

1. Bearbeite die Datei package.json für dein Paket, und füge einen publishConfig-Eintrag ein.

   "publishConfig": {
     "registry": "https://npm.pkg.github.com"
   },
   

2. Überprüfe das Feld repository in der Datei package.json deines Projekts. Das Feld repository muss mit der URL für Ihr GitHub-Repository übereinstimmen. Wenn ihre Repository-URL beispielsweise github.com/my-org/test lautet, sollte das Repositoryfeld https://github.com/my-org/test.git lauten.

3. Das Paket veröffentlichen:

   npm publish
   

Veröffentlichen mehrerer Pakete im gleichen Repository

Wenn du mehrere Pakete im selben Repository veröffentlichen und verlinken möchtest, kannst du die URL des GitHub-Repositorys im Feld repository der Datei package.json einfügen. Weitere Informationen findest du unter Erstellen einer package.json-Datei und Erstellen von Node.js-Modulen in der npm-Dokumentation.

Wenn du sicherstellen möchtest, dass die URL des Repositorys korrekt ist, ersetze REPOSITORY durch den Namen des Repositorys, das das zu veröffentlichende Paket enthält, und OWNER durch den Namen des persönlichen Kontos oder der Organisation auf GitHub, in dessen Besitz sich das Repository befindet.

GitHub Packages passt das Repository anhand der URL.

"repository":"https://github.com/OWNER/REPOSITORY",

Installieren eines Pakets

Du kannst Pakete aus GitHub Packages installieren, indem du die Pakete als Abhängigkeiten in der Datei package.json für dein Projekt hinzufügst. Weitere Informationen zum Verwenden einer package.json-Datei in deinem Projekt findest du unter Arbeiten mit package.json in der npm-Dokumentation.

Du kannst Pakete standardmäßig aus einer Organisation hinzufügen. Weitere Informationen findest du unter Installieren von Paketen aus anderen Organisationen.

Du musst außerdem die Datei .npmrc zu deinem Projekt hinzufügen, damit alle Anforderungen zum Installieren von Paketen an GitHub Packages weitergeleitet werden. Wenn du alle Paketanforderungen über GitHub Packages weiterleitest, kannst du sowohl Pakete mit Geltungsbereich als auch Pakete ohne Geltungsbereich von npmjs.com verwenden. Weitere Informationen findest du unter npm-scope in der npm-Dokumentation.

1. Authentifizieren bei GitHub Packages. Weitere Informationen findest Du unter Authentifizieren bei GitHub Packages.

2. Erstelle oder bearbeite eine .npmrc-Datei in demselben Verzeichnis wie deine package.json-Datei, um eine Zeile einzuschließen, die die GitHub Packages-URL und den Namespace angibt, in dem das Paket gehostet wird. Ersetze NAMESPACE durch den Namen des Benutzer- oder Organisationskontos , auf das das Paket ausgerichtet wird.

   @NAMESPACE:registry=https://npm.pkg.github.com
   

3. Füge die NPMRC-Datei dem Repository hinzu, in dem GitHub Packages dein Projekt finden kann. Weitere Informationen findest du unter Eine Datei zu einem Repository hinzufügen.

4. Konfiguriere package.json in deinem Projekt, um das Paket zu verwenden, das du installierst. Gib den vollständigen Paketnamen an (z. B. @my-org/server), um die Paketabhängigkeiten zur Datei package.json für GitHub Packages hinzuzufügen. Gib für Pakete aus npmjs.com den vollständigen Namen (z. B. @babel/core oder lodash) an. Ersetze ORGANIZATION_NAME/PACKAGE_NAME durch deine Paketabhängigkeit.

   {
     "name": "@my-org/server",
     "version": "1.0.0",
     "description": "Server app that uses the ORGANIZATION_NAME/PACKAGE_NAME package",
     "main": "index.js",
     "author": "",
     "license": "MIT",
     "dependencies": {
       "ORGANIZATION_NAME/PACKAGE_NAME": "1.0.0"
     }
   }
   

5. Installiere das Paket.

   npm install
   

Pakete von anderen Organisationen installieren

Standardmäßig kannst du nur GitHub Packages-Pakete von einer Organisation verwenden. Wenn du Paketanforderungen an mehrere Organisationen und Benutzer*innen weiterleiten möchtest, kannst du der .npmrc-Datei zusätzliche Zeilen hinzufügen und NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation ersetzen.

@NAMESPACE:registry=https://npm.pkg.github.com
@NAMESPACE:registry=https://npm.pkg.github.com