Gérer les packages Node.js

Cette page décrit les tâches suivantes :

• Afficher et supprimer des packages et des versions de packages
• Afficher, créer, mettre à jour et supprimer des tags

Avant de commencer

1. Si le dépôt cible n'existe pas, créez un dépôt.
2. Vérifiez que vous disposez des autorisations requises pour le dépôt.
3. Configurez l'authentification pour npm.
4. (Facultatif) Configurez des valeurs par défaut pour les commandes gcloud.
5. Si vous utilisez l'assistant d'identification npm pour l'authentification, obtenez un jeton d'accès avant de vous connecter à un dépôt avec npm.

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer les packages, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le dépôt :

• Afficher les packages, les fichiers dans les packages et les tags : Lecteur Artifact Registry (roles/artifactregistry.reader)
• Télécharger ou installer des packages : Lecteur Artifact Registry (roles/artifactregistry.reader)
• Ajouter des packages à un dépôt : Rédacteur Artifact Registry (roles/artifactregistry.writer)
• Supprimer des packages : Administrateur de dépôts Artifact Registry (roles/artifactregistry.repoAdmin)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Obtenir un jeton d'accès

Les jetons d'accès sont valables pendant 60 minutes. Générez un jeton d'accès peu de temps avant d'exécuter des commandes qui interagissent avec les dépôts.

Pour obtenir un jeton, utilisez l'une des options suivantes :

• Utilisez la commande npx pour actualiser le jeton d'accès.

  1. Assurez-vous que les identifiants de connexion au registre npm public se trouvent dans votre fichier de configuration npm d'utilisateur ~/.npmrc.

  2. Exécutez la commande suivante dans le répertoire de votre projet Node.js.

     npx google-artifactregistry-auth
     

     Si votre dépôt Artifact Registry est défini comme registre global et que vos packages ne sont pas limités, utilisez plutôt la commande suivante pour que la commande puisse télécharger le programme d'assistance pour les identifiants à partir du registre npm public au lieu de votre dépôt Artifact Registry.

     npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
     

• Ajoutez un script au fichier package.json dans votre projet.

  "scripts": {
   "artifactregistry-login": "npx google-artifactregistry-auth"
  }
  

  Exécutez le script dans le répertoire de votre projet Node.js.

  npm run artifactregistry-login
  

Artifact Registry lit les paramètres du dépôt Artifact Registry dans le fichier .npmrc de votre projet et les utilise pour ajouter des identifiants de jeton à votre fichier .npmrc utilisateur. Le stockage du jeton dans votre fichier .npmrc utilisateur isole vos identifiants de votre code source et de votre système de gestion de code source.

Ajouter des packages

Modes de dépôt : standard

Vous ne pouvez publier une version spécifique d'un package qu'une seule fois. Il s'agit d'une restriction npm pour garantir que le contenu d'une version de package publiée est toujours identique. Par conséquent, vous ne pouvez pas :

• Écraser une version de package en la republiant dans le dépôt
• Supprimer un package ou sa version du dépôt, puis publier un package portant le même nom et le même numéro de version

Si vous ne spécifiez pas de tag lorsque vous publiez un package, npm ajoute le tag latest. Pour simplifier l'installation de vos packages à une étape de développement spécifique, envisagez de les publier avec un tag, tel que beta ou dev.

Artifact Registry applique des noms de packages alphanumériques en minuscules pour les packages npm.

Pour ajouter un package :

1. Assurez-vous que le nom du package dans package.json inclut le champ d'application configuré pour votre dépôt. L'exemple suivant présente un package dont le champ d'application est dev-repo.

   "name": "@dev-repo/my-package"
   

2. Si vous utilisez l'assistant d'identification pour vous authentifier avec un jeton d'accès, obtenez un nouveau jeton.

3. Ajoutez des packages au dépôt. Vous pouvez utiliser une commande npm ou yarn.

   Pour taguer le package, incluez l'option --tag et remplacez TAG par le tag que vous souhaitez utiliser. Si vous n'incluez pas l'option --tag, npm définit automatiquement le tag sur latest.

   npm publish --tag=TAG
   

   yarn publish --tag TAG
   

Afficher des packages et des versions

Modes de dépôt : standard, distant, virtuel

Pour obtenir des informations sur le package avec npm ou yarn :

1. Si vous utilisez l'assistant d'identification pour vous authentifier avec un jeton d'accès, obtenez un nouveau jeton.

2. Exécutez la commande appropriée :

   npm view
   

   yarn info
   

Pour afficher les packages et les versions de package à l'aide de la console Google Cloud ou de gcloud:

Console

1. Ouvrez la page Dépôts dans la console Google Cloud .

   Ouvrir la page "Dépôts"

2. Dans la liste des dépôts, cliquez sur le dépôt approprié.

   La page Packages répertorie les packages du dépôt.

3. Cliquez sur un package pour afficher ses versions.

gcloud

Pour répertorier les packages d'un dépôt, exécutez la commande suivante :

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

Remplacez les éléments suivants :

• REPOSITORY est le nom du dépôt. Si vous avez configuré un dépôt par défaut, vous pouvez omettre cet indicateur pour utiliser le dépôt par défaut.
• LOCATION est l'emplacement régional ou multirégional du dépôt. Si vous avez configuré un emplacement par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.

Pour afficher les versions d'un package, exécutez la commande suivante :

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Remplacez les éléments suivants :

• PACKAGE est l'ID du package ou l'identifiant complet du package.
• REPOSITORY est le nom du dépôt. Si vous avez configuré un dépôt par défaut, vous pouvez omettre cet indicateur pour utiliser le dépôt par défaut.
• LOCATION est l'emplacement régional ou multirégional du dépôt. Utilisez cette option pour afficher les dépôts dans un emplacement spécifique. Si vous avez configuré un emplacement par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.

L'affichage des packages et des versions depuis la console Google Cloud ou la gcloud CLI n'est disponible que pour les dépôts standards et distants.

Pour les dépôts distants, la liste renvoyée doit inclure toutes les dépendances directes et transitives mises en cache dans le dépôt.

Lister les fichiers

Modes de dépôt : standard, distant

Vous pouvez lister les fichiers d'un dépôt, les fichiers de toutes les versions d'un package spécifié ou les fichiers d'une version spécifique d'un package.

Pour toutes les commandes suivantes, vous pouvez définir un nombre maximal de fichiers à renvoyer en ajoutant l'option --limit à la commande.

Pour répertorier tous les fichiers dans le projet, le dépôt et l'emplacement par défaut lorsque les valeurs par défaut sont configurées :

gcloud artifacts files list

Pour lister les fichiers d'un projet, d'un dépôt et d'un emplacement spécifiques, exécutez la commande suivante :

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

Pour lister les fichiers de toutes les versions d'un package spécifique :

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

Pour lister les fichiers d'une version de package spécifique :

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

Pour lister les fichiers d'un tag spécifique :

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

Remplacez les valeurs suivantes :

• LOCATION : emplacement régional ou multirégional du dépôt.
• PROJECT : ID de votre projet Google Cloud . Si l'ID du projet contient le signe deux-points (:), consultez la section Projets à l'échelle du domaine.
• REPOSITORY : nom du dépôt où l'image est stockée.
• PACKAGE : nom du package.
• VERSION : version du package.
• TAG : tag associé au package.

Exemples

Considérez les informations suivantes sur le package :

• Projet : my-project
• Dépôt : my-repo
• Emplacement du dépôt : us-west1
• Package : my-app

La commande suivante liste tous les fichiers du dépôt my-repo à l'emplacement us-west1 dans le projet par défaut :

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

La commande suivante liste les fichiers de la version 1.0 du package.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

La commande suivante liste les fichiers dans la version du package avec le tag 1.0-dev.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

Ajout de tags aux packages

Modes de dépôt : standard

You can view, add, update, and delete tags. Tags can help you manage semantic versions of your packages and streamline installation of packages at a specific stage of development.

For example, you can tag the current release candidate build with rc. Your team can then install the correct version based on the tag instead of a version specifier, and unpublishing unused pre-release versions won't break your dependencies on the release candidate package.

Viewing tags

To view tags for a package:

Console

1. Open the Repositories page in the Google Cloud console.

   Ouvrir la page "Dépôts"

2. Click the package to view versions and the associated tags.

3. Select the package version to tag.

4. In the row of the selected version, click More actions (), and then click Edit tags.

5. Type new tags into the field and then click SAVE.

gcloud

Run the command:

gcloud artifacts tags list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Where

• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
• LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

For example, to view tags for the package my-package in the repository my-repo in the default location, run the command:

gcloud artifacts tags list --package=my-pkg --repository=my-repo

Creating tags

You can create a tag for a specific version of a package.

To tag an existing image in a repository:

Console

1. Open the Repositories page in the Google Cloud console.

   Ouvrir la page "Dépôts"

2. Click the package to view versions of the package.

3. Select the package version to tag.

4. In the row of the selected version, click More actions (), and then click Edit tags.

5. Type new tags into the field and then click SAVE.

gcloud

Run the following command:

gcloud artifacts tags create TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

Where

• TAG is the tag you want to apply to the package.
• PACKAGE is the name of the package in the repository.
• VERSION is version of the package that you want to tag.
• LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to create the tag release-candidate for version 1.0.0 of package my-package in the repository my-repo in the default location, run the command:

gcloud artifacts tags create release-candidate --version=1.0.0 \
    --package=my-pkg --repository=my-repo

Updating tags

You can change a tag associated with a package version.

To change an existing tag:

Console

1. Open the Repositories page in the Google Cloud console.

   Ouvrir la page "Dépôts"

2. Click the package to view versions of the package.

3. Select the package version with the tag to change.

4. In the row of the selected version, click More actions (), and then click Edit tags.

5. Edit the tag and then click SAVE.

gcloud

Run the following command:

gcloud artifacts tags update TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

Where

• TAG is the tag you want to apply to the package.
• PACKAGE is the name of the package in the repository.
• VERSION is version of the package that you want to tag.
• LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to change the tag for version 1.0.0 of package my-package to production in the repository my-repo in the default location, run the command:

gcloud artifacts tags update production --version=1.0.0 \
    --package=my-pkg --repository=my-repo

Untagging package versions

You can remove an existing tag from a package version.

To remove a tag:

Console

1. Open the Repositories page in the Google Cloud console.

   Ouvrir la page "Dépôts"

2. Click the image to view versions of the image.

3. Select the image version to untag.

4. In the row of the selected version, click More actions (), and then click Edit tags.

5. Delete the tag and then click SAVE.

gcloud

Run the following command:

gcloud artifacts tags delete TAG --package=PACKAGE \
    [--location=<LOCATION] [--repository=REPOSITORY]

Where

• TAG is the tag you want to apply to the package.
• PACKAGE is the name of the package in the repository.
• LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to remove the tag release-candidate from package my-package in the repository my-repo in the default location, run the command:

gcloud artifacts tags delete release-candidate --package=my-pkg \
    --repository=my-repo

Installer des packages

Modes de dépôt : standard, distant, virtuel

Pour installer un package à partir du dépôt de packages Node.js :

1. Si vous utilisez l'assistant d'identification pour vous authentifier avec un jeton d'accès, obtenez un nouveau jeton.

2. Utilisez la commande npm install ou yarn add.

   npm

   Pour installer la version avec le tag latest :

   npm install @SCOPE/PACKAGE
   

   Pour installer une version avec un tag différent :

   npm install @SCOPE/PACKAGE@TAG
   

   Pour installer une version spécifique :

   npm install @SCOPE/PACKAGE@VERSION
   

   yarn

   Pour installer la version avec le tag latest :

   yarn add @SCOPE/PACKAGE
   

   Pour installer une version avec un tag différent :

   yarn add @SCOPE/PACKAGE@TAG
   

   Pour installer une version spécifique :

   yarn add @SCOPE/PACKAGE@VERSION
   

   Remplacez les valeurs suivantes :

   • SCOPE est le champ d'application associé au dépôt. Si votre dépôt de packages Node.js n'est pas configuré avec un champ d'application, omettez @SCOPE/ dans la commande.
   • PACKAGE est le nom du package dans le dépôt.
   • TAG est le tag de la version que vous souhaitez installer.
   • VERSION correspond au numéro de version que vous souhaitez installer.

Lorsque vous spécifiez un package en tant que dépendance dans package.json, veillez à inclure le champ d'application du dépôt. L'exemple suivant montre le champ d'application @dev-repo d'un package nommé my-package.

"dependencies": {
  "@dev-repo/my-package": ">=1.0.0"
}

Pour les dépôts standards, vous téléchargez un package directement à partir du dépôt.

Pour un dépôt distant, vous téléchargez une copie mise en cache du package et de ses dépendances. Si aucune copie mise en cache n'existe, le dépôt distant télécharge le package à partir de la source en amont et le met en cache avant de vous le fournir. Vous pouvez vérifier que le dépôt distant a récupéré les packages à partir de la source en amont en affichant la liste des packages dans le dépôt.

Pour un dépôt virtuel, Artifact Registry recherche le package demandé dans les dépôts en amont.

• Les dépôts distants en amont téléchargeront et mettront en cache le package demandé si aucune copie mise en cache n'existe. Les dépôts virtuels ne font que diffuser les packages demandés, ils ne les stockent pas.
• Si vous demandez une version disponible dans plusieurs dépôts en amont, Artifact Registry choisit un dépôt en amont à utiliser en fonction des paramètres de priorité configurés pour le dépôt virtuel.

Prenons l'exemple d'un dépôt virtuel avec les paramètres de priorité suivants pour les dépôts en amont :

• main-repo : priorité définie sur 100
• secondary-repo1 : la priorité est définie sur 80.
• secondary-repo2 : la priorité est définie sur 80.
• test-repo : la priorité est définie sur 20.

main-repo a la valeur de priorité la plus élevée. Le dépôt virtuel le recherche donc toujours en premier.

Les priorités de secondary-repo1 et secondary-repo2 sont définies sur 80. Si un package demandé n'est pas disponible dans main-repo, Artifact Registry recherche ensuite dans ces dépôts. Comme ils ont tous les deux la même valeur de priorité, Artifact Registry peut choisir de diffuser un package à partir de l'un ou l'autre dépôt si la version est disponible dans les deux.

test-repo a la valeur de priorité la plus basse et diffusera un artefact stocké si aucun des autres dépôts en amont ne le possède.

Supprimer des packages

Modes de dépôt : standard, distant

Vous pouvez supprimer un package et toutes ses versions, ou supprimer une version spécifique.

• La suppression d'un package est irréversible.
• Pour les dépôts distants, seule la copie mise en cache du package est supprimée. La source en amont n'est pas affectée. Si vous supprimez un package mis en cache, Artifact Registry le téléchargera et le mettra à nouveau en cache la prochaine fois que le dépôt recevra une demande pour la même version du package.

Une fois la version de package publiée, vous ne pouvez pas republier un package du même nom et de la même version, même après la suppression de la version. Il s'agit d'une restriction npm pour garantir que le contenu d'une version de package publiée est toujours identique.

Si vous souhaitez encourager les utilisateurs à installer une version mise à jour du package, exécutez la commande npm deprecate pour marquer l'ancienne version du package comme étant obsolète. Lorsqu'un utilisateur tente d'installer le package obsolète, Artifact Registry renvoie un avertissement d'obsolescence.

Avant de supprimer un package ou une version de package, vérifiez que vous avez communiqué ou résolu toute dépendance importante associée.

Pour supprimer un package, procédez comme suit :

Console

1. Ouvrez la page Dépôts dans la console Google Cloud .

   Ouvrir la page "Dépôts"

2. Dans la liste des dépôts, cliquez sur le dépôt approprié.

   La page Packages répertorie les packages du dépôt.

3. Sélectionnez le package que vous souhaitez supprimer.

4. Cliquez sur SUPPRIMER.

5. Dans la boîte de dialogue de confirmation, cliquez sur SUPPRIMER.

gcloud

Exécutez la commande ci-dessous.

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Remplacez les éléments suivants :

• PACKAGE est le nom du package dans le dépôt.
• REPOSITORY est le nom du dépôt. Si vous avez configuré un dépôt par défaut, vous pouvez omettre cet indicateur pour utiliser le dépôt par défaut.
• LOCATION est l'emplacement régional ou multirégional du dépôt. Utilisez cette option pour afficher les dépôts dans un emplacement spécifique. Si vous avez configuré un emplacement par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.

L'option --async permet à la commande de renvoyer immédiatement une réponse, sans attendre la fin de l'opération en cours.

Pour supprimer des versions d'un package, procédez comme suit :

Console

1. Ouvrez la page Dépôts dans la console Google Cloud .

   Ouvrir la page "Dépôts"

2. Dans la liste des dépôts, cliquez sur le dépôt approprié.

   La page Packages répertorie les packages du dépôt.

3. Cliquez sur un package pour afficher ses versions.

4. Sélectionnez les versions que vous souhaitez supprimer.

5. Cliquez sur SUPPRIMER.

6. Dans la boîte de dialogue de confirmation, cliquez sur SUPPRIMER.

gcloud

Exécutez la commande ci-dessous.

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Remplacez les éléments suivants :

• VERSION correspond au nom de la version à supprimer.
• PACKAGE est le nom du package dans le dépôt.
• REPOSITORY est le nom du dépôt. Si vous avez configuré un dépôt par défaut, vous pouvez omettre cet indicateur pour utiliser le dépôt par défaut.
• LOCATION est l'emplacement régional ou multirégional du dépôt. Utilisez cette option pour afficher les dépôts dans un emplacement spécifique. Si vous avez configuré un emplacement par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.

L'option --async permet à la commande de renvoyer immédiatement une réponse, sans attendre la fin de l'opération en cours.

Étapes suivantes

• En savoir plus sur la gestion des packages Maven
• En savoir plus sur la gestion des images de conteneurs
• Télécharger des fichiers individuels dans un package