Authentification auprès de GitHub Packages
GitHub Packages prend uniquement en charge l’authentification à l’aide d’un personal access token (classic). Pour plus d’informations, consultez « Gestion de vos jetons d’accès personnels ».
Vous avez besoin d’un jeton d’accès pour publier, installer et supprimer des packages privés, internes et publics.
Vous pouvez utiliser un personal access token (classic) pour vous authentifier sur GitHub Packages ou l’API GitHub. Quand vous créez un personal access token (classic), vous pouvez l’attribuer à différentes étendues selon vos besoins. Pour plus d’informations sur les étendues liées aux packages pour un personal access token (classic), consultez « À propos des autorisations pour les packages GitHub ».
Pour vous authentifier sur un registre GitHub Packages dans un workflow GitHub Actions, vous pouvez utiliser :
GITHUB_TOKEN
pour publier des packages associés au dépôt du workflow.- un personal access token (classic) avec au moins l’étendue
read:packages
pour installer des packages associés à d’autres dépôts privés (auxquelsGITHUB_TOKEN
ne peut pas accéder).
Authentification dans un workflow GitHub Actions
Ce registre prend en charge les autorisations granulaires. Pour les registres prenant en charge les autorisations granulaires, si votre workflow GitHub Actions utilise un personal access token pour s’authentifier auprès d’un registre, nous vous recommandons vivement de mettre à jour votre workflow pour utiliser GITHUB_TOKEN
. Pour obtenir des conseils sur la mise à jour de vos workflows qui s’authentifient auprès d’un registre avec un personal access token, consultez « Publication et installation d’un package avec GitHub Actions ».
Remarque : la capacité des workflows GitHub Actions de supprimer et de restaurer des packages à l’aide de l’API REST est actuellement en version bêta publique et susceptible d’être modifiée.
Vous pouvez utiliser un GITHUB_TOKEN
dans un workflow GitHub Actions pour supprimer ou restaurer un package via l’API REST si le jeton dispose de l’autorisation admin
sur le package. Les référentiels qui publient des packages à l’aide d’un workflow et les référentiels que vous avez explicitement connectés à des packages se voient automatiquement accorder l’autorisation admin
aux packages dans le référentiel.
Pour plus d’informations sur GITHUB_TOKEN
, consultez « Authentification par jeton automatique ». Pour plus d’informations sur les bonnes pratiques lors de l’utilisation d’un registre dans des actions, consultez « Durcissement de la sécurité pour GitHub Actions ».
Vous pouvez également choisir d’accorder des autorisations d’accès aux packages indépendamment pour GitHub Codespaces et GitHub Actions. Pour plus d’informations, consultez « Configuration du contrôle d’accès et de la visibilité d’un package » et « Configuration du contrôle d’accès et de la visibilité d’un package ».
Authentification avec un personal access token
Vous devez utiliser un personal access token (classic) avec les étendues appropriées pour publier et installer des packages dans GitHub Packages. Pour plus d’informations, consultez « Présentation de GitHub Packages ».
Vous pouvez vous authentifier auprès de GitHub Packages avec npm en modifiant votre fichier ~/.npmrc spécifique à l’utilisateur pour y inclure votre personal access token (classic), ou en vous connectant à npm sur la ligne de commande en utilisant votre nom d’utilisateur et personal access token.
Pour vous authentifier en ajoutant votre personal access token (classic) à votre fichier ~/.npmrc, modifiez le fichier ~/.npmrc pour votre projet afin d’y inclure la ligne suivante, en remplaçant TOKEN par votre personal access token. Créez un fichier ~/.npmrc s’il n’en existe pas.
//npm.pkg.github.com/:_authToken=TOKEN
Pour vous authentifier en vous connectant à npm, utilisez la commande npm login
, en remplaçant USERNAME par votre nom d’utilisateurGitHub, TOKEN par votre personal access token (classic) et PUBLIC-EMAIL-ADDRESS par votre adresse e-mail.
Si vous utilisez l’interface CLI NPM version 9 ou ultérieure, et que vous vous connectez un registre privé ou que vous vous en déconnectez à l’aide de la ligne de commande, vous devez utiliser l’option --auth-type=legacy
pour lire les détails de votre authentification à partir d’invites au lieu d’utiliser le flux de connexion par défaut via un navigateur. Pour plus d’informations, consultez npm-login
.
Si GitHub Packages n’est pas votre registre de packages par défaut pour utiliser npm et que vous souhaitez utiliser la commande npm audit
, nous vous recommandons d’utiliser l’indicateur --scope
avec l’espace de noms qui héberge le package (le compte personnel ou l’organisation
auxquels le package est délimité) lorsque vous vous authentifiez auprès de GitHub Packages.
$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://npm.pkg.github.com
> Username: USERNAME
> Password: TOKEN
Publication d’un package
Remarque :
- Les noms et les étendues des packages doivent utiliser seulement des lettres minuscules.
- Le tarball d’une version npm doit être inférieur à 256 Mo.
Le registre GitHub Packages stocke les packages npm au sein de votre compte d’organisation ou personnel, et vous permet d’associer un package à un dépôt. Vous pouvez choisir d’hériter des autorisations d’un dépôt ou de définir des autorisations granulaires indépendamment d’un dépôt.
Lorsque vous publiez un package pour la première fois, la visibilité par défaut est privée. Pour modifier la visibilité ou définir les autorisations d’accès, consultez « Configuration du contrôle d’accès et de la visibilité d’un package ». Pour plus d’informations sur la liaison d’un package publié à un dépôt, consultez « Connexion d’un dépôt à un package ».
Vous pouvez connecter un package à un dépôt dès que le package est publié en incluant un champ repository
dans le fichier package.json
. Vous pouvez également utiliser cette méthode pour connecter plusieurs packages au même dépôt. Pour plus d’informations, consultez « Publication de plusieurs packages sur le même dépôt ».
Remarque : Si vous publiez un package lié à un dépôt, le package hérite automatiquement des autorisations d’accès du dépôt lié, tandis que les workflows GitHub Actions du dépôt lié accèdent automatiquement au package, sauf si votre organisation a désactivé l’héritage automatique des autorisations d’accès. Pour plus d’informations, consultez « Configuration du contrôle d’accès et de la visibilité d’un package ».
Vous pouvez configurer le mappage d’étendue pour votre projet en utilisant un fichier .npmrc
local dans le projet ou en utilisant l’option publishConfig
dans le package.json
. GitHub Packages prend en charge seulement les packages npm délimités. Les packages délimités ont des noms au format @NAMESPACE/PACKAGE-NAME
. Les packages délimités commencent toujours par un symbole @
. Il peut être nécessaire de mettre à jour le nom dans votre package.json
pour utiliser le nom délimité. Par exemple, si vous êtes l’utilisateur octocat
et que votre package s’appelle test
, vous devez affecter le nom de package délimité comme suit : "name": "@octocat/test"
.
Après avoir publié un package, vous pouvez l’afficher sur GitHub. Pour plus d’informations, consultez « Affichage de packages ».
Publication d’un package en utilisant un fichier .npmrc local
Vous pouvez utiliser un fichier .npmrc pour configurer le mappage d’étendue pour votre projet. Dans le fichier .npmrc, utilisez l’URL et le propriétaire du compte GitHub Packages pour permettre à GitHub Packages de savoir où router les demandes de package. L’utilisation d’un fichier .npmrc empêche d’autres développeurs de publier accidentellement le package sur npmjs.org au lieu de le faire sur GitHub Packages.
-
Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez « Authentification auprès de GitHub Packages ».
-
Dans le même répertoire que votre fichier
package.json
, créez ou modifiez un fichier.npmrc
pour inclure une ligne spécifiant l’URL de GitHub Packages et l’espace de noms où le package est hébergé. RemplacezNAMESPACE
par le nom du compte d’utilisateur ou d’organisation auquel le package sera délimité.@NAMESPACE:registry=https://npm.pkg.github.com
-
Ajoutez le fichier .npmrc au dépôt où GitHub Packages peut trouver votre projet. Pour plus d’informations, consultez « Ajout d’un fichier à un référentiel ».
-
Vérifiez le nom de votre package dans le
package.json
de votre projet. Le champname
doit contenir l’étendue et le nom du package. Par exemple, si votre package est appelé « test » et que vous publiez sur l’organisation GitHub « My-org », le champname
de votrepackage.json
doit être@my-org/test
. -
Vérifiez le champ
repository
dans le fichier package.json de votre projet. Le champrepository
doit correspondre à l’URL de votre référentiel GitHub. Par exemple, si l’URL de votre référentiel estgithub.com/my-org/test
, le champ du référentiel doit êtrehttps://github.com/my-org/test.git
. -
Publiez le package :
npm publish
Publication d’un package en utilisant publishConfig
dans le fichier package.json
Vous pouvez utiliser l’élément publishConfig
dans le fichier package.json
pour spécifier le registre où vous voulez que le package soit publié. Pour plus d’informations, consultez « publishConfig » dans la documentation npm.
-
Modifiez le fichier
package.json
pour votre package et incluez-y une entréepublishConfig
."publishConfig": { "registry": "https://npm.pkg.github.com" },
- Vérifiez le champ
repository
dans le fichier package.json de votre projet. Le champrepository
doit correspondre à l’URL de votre référentiel GitHub. Par exemple, si l’URL de votre référentiel estgithub.com/my-org/test
, le champ du référentiel doit êtrehttps://github.com/my-org/test.git
.
- Vérifiez le champ
-
Publiez le package :
npm publish
Publication de plusieurs packages sur le même dépôt
Pour publier plusieurs packages et les lier sur le même dépôt, vous pouvez inclure l’URL du dépôt GitHub dans le champ repository
du fichier package.json
pour chaque package. Pour plus d’informations, consultez « Création d’un fichier package.json » et « Création de modules Node.js » dans la documentation npm.
Pour garantir que l’URL du dépôt est correcte, remplacez REPOSITORY
par le nom du dépôt contenant le package que vous voulez publier, et OWNER
par le nom du compte personnel ou de l’organisation sur GitHub qui est propriétaire du dépôt.
GitHub Packages établira une correspondance avec le dépôt en fonction de l’URL.
"repository":"https://github.com/OWNER/REPOSITORY",
Installation d’un package
Vous pouvez installer des packages depuis GitHub Packages en ajoutant les packages en tant que dépendances dans le fichier package.json
pour votre projet. Pour plus d’informations sur l’utilisation d’un fichier package.json
dans votre projet, consultez « Utilisation d’un package.json » dans la documentation npm.
Par défaut, vous pouvez ajouter des packages provenant d’une seule organisation. Pour plus d’informations, consultez « Installation de packages provenant d’autres organisations ».
Vous devez aussi ajouter le fichier .npmrc à votre projet afin que toutes les demandes d’installation de packages passent par GitHub Packages. Quand vous routez toutes les demandes de package via GitHub Packages, vous pouvez utiliser à la fois des packages délimités et des packages non délimités provenant de npmjs.org. Pour plus d’informations, consultez « npm-scope » dans la documentation npm.
-
Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez « Authentification auprès de GitHub Packages ».
-
Dans le même répertoire que votre fichier
package.json
, créez ou modifiez un fichier.npmrc
pour inclure une ligne spécifiant l’URL de GitHub Packages et l’espace de noms où le package est hébergé. RemplacezNAMESPACE
par le nom du compte d’utilisateur ou d’organisation auquel le package sera délimité.@NAMESPACE:registry=https://npm.pkg.github.com
-
Ajoutez le fichier .npmrc au dépôt où GitHub Packages peut trouver votre projet. Pour plus d’informations, consultez « Ajout d’un fichier à un référentiel ».
-
Configurez
package.json
dans votre projet afin d’utiliser le package que vous installez. Pour ajouter vos dépendances de package au fichierpackage.json
pour GitHub Packages, spécifiez le nom du package entièrement délimité, comme@my-org/server
. Pour les packages provenant de npmjs.com, spécifiez le nom complet, comme@babel/core
ou@lodash
. RemplacezORGANIZATION_NAME/PACKAGE_NAME
par votre dépendance de package.{ "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" } }
-
Installez le package.
npm install
Installation de packages provenant d’autres organisations
Par défaut, vous pouvez seulement utiliser des packages GitHub Packages provenant d’une seule organisation. Si vous souhaitez acheminer les demandes de package vers plusieurs organisations et utilisateurs, vous pouvez ajouter des lignes supplémentaires à votre fichier .npmrc, en remplaçant NAMESPACE
par le nom du compte personnel ou de l’organisation auxquels le package est délimité.
@NAMESPACE:registry=https://npm.pkg.github.com
@NAMESPACE:registry=https://npm.pkg.github.com