Gestionar paquetes de Node.js

En esta página se describen las siguientes tareas:

• Ver y eliminar paquetes y versiones de paquetes
• Ver, crear, actualizar y eliminar etiquetas

Antes de empezar

1. Si el repositorio de destino no existe, crea uno.
2. Verifica que tienes los permisos necesarios para el repositorio.
3. Configura la autenticación para npm.
4. (Opcional) Configura los valores predeterminados de los comandos de gcloud.
5. Si usas el asistente de credenciales de npm para la autenticación, obtén un token de acceso antes de conectarte a un repositorio con npm.

Roles obligatorios

Para obtener los permisos que necesitas para gestionar paquetes, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en el repositorio:

• Ver paquetes, archivos de paquetes y etiquetas: Lector de Artifact Registry (roles/artifactregistry.reader)
• Descargar o instalar paquetes: Lector de Artifact Registry (roles/artifactregistry.reader)
• Añadir paquetes a un repositorio: Escritor de Artifact Registry (roles/artifactregistry.writer)
• Eliminar paquetes: Administrador de repositorios de Artifact Registry (roles/artifactregistry.repoAdmin)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Obtener un token de acceso

Los tokens de acceso son válidos durante 60 minutos. Genera un token de acceso poco antes de ejecutar comandos que interactúen con repositorios.

Para obtener un token, utiliza una de estas opciones:

• Usa el comando npx para actualizar el token de acceso.

  1. Asegúrate de que las credenciales para conectarte al registro público de npm estén en el archivo de configuración de npm de tu usuario, ~/.npmrc.

  2. Ejecuta el siguiente comando en el directorio de tu proyecto Node.js.

     npx google-artifactregistry-auth
     

     Si tu repositorio de Artifact Registry está configurado como registro global y tus paquetes no tienen un ámbito definido, usa el siguiente comando para que el comando pueda descargar el asistente de credenciales del registro público de npm en lugar de tu repositorio de Artifact Registry.

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

• Añade una secuencia de comandos al archivo package.json de tu proyecto.

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

  Ejecuta la secuencia de comandos en el directorio del proyecto de Node.js.

  npm run artifactregistry-login
  

Artifact Registry lee los ajustes del repositorio de Artifact Registry en el archivo .npmrc de tu proyecto y los usa para añadir credenciales de token al archivo .npmrc de tu usuario. Almacenar el token en el archivo .npmrc del usuario aísla tus credenciales de tu código fuente y de tu sistema de control de código fuente.

Añadir paquetes

Modos de repositorio: estándar

Solo puedes publicar una versión específica de un paquete una vez. Se trata de una restricción de npm para asegurarse de que el contenido de una versión publicada de un paquete sea siempre el mismo. Por lo tanto, no puedes hacer lo siguiente:

• Sobrescribir una versión de un paquete publicándola de nuevo en el repositorio
• Eliminar un paquete o su versión del repositorio y, a continuación, publicar un paquete con el mismo nombre y número de versión

Si no especificas una etiqueta al publicar un paquete, npm añade la etiqueta latest. Para simplificar la instalación de tus paquetes en una fase de desarrollo específica, te recomendamos que los publiques con una etiqueta, como beta o dev.

Artifact Registry aplica nombres de paquetes alfanuméricos en minúsculas para los paquetes npm.

Para añadir un paquete, sigue estos pasos:

1. Asegúrate de que el nombre del paquete en package.json incluya el ámbito configurado para tu repositorio. En el siguiente ejemplo se muestra un paquete con el ámbito dev-repo.

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

2. Si usas el asistente de credenciales para autenticarte con un token de acceso, obtén un nuevo token.

3. Añade paquetes al repositorio. Puedes usar el comando npm o yarn.

   Para etiquetar el paquete, incluye la marca --tag y sustituye TAG por la etiqueta que quieras usar. Si no incluye la marca --tag, npm asignará automáticamente la etiqueta latest.

   npm publish --tag=TAG
   

   yarn publish --tag TAG
   

Ver paquetes y versiones

Modos de repositorio: estándar, remoto y virtual

Para obtener información sobre un paquete con npm o yarn, sigue estos pasos:

1. Si usas el asistente de credenciales para autenticarte con un token de acceso, obtén un nuevo token.

2. Ejecuta el comando adecuado:

   npm view
   

   yarn info
   

Para ver los paquetes y las versiones de los paquetes mediante la consola Google Cloud o gcloud, sigue estos pasos:

Consola

1. Abre la página Repositorios en la consola de Google Cloud .

   Abre la página Repositorios.

2. En la lista de repositorios, haga clic en el repositorio correspondiente.

   En la página Paquetes se muestran los paquetes del repositorio.

3. Haz clic en un paquete para ver sus versiones.

gcloud

Para enumerar los paquetes de un repositorio, ejecuta el siguiente comando:

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

Haz los cambios siguientes:

• REPOSITORY es el nombre del repositorio. Si has configurado un repositorio predeterminado, puedes omitir esta marca para usarlo.
• LOCATION es la ubicación regional o multirregional del repositorio. Si has configurado una ubicación predeterminada, puedes omitir esta marca para usarla.

Para ver las versiones de un paquete, ejecuta el siguiente comando:

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

Haz los cambios siguientes:

• PACKAGE es el ID del paquete o el identificador completo del paquete.
• REPOSITORY es el nombre del repositorio. Si has configurado un repositorio predeterminado, puedes omitir esta marca para usarlo.
• LOCATION es la ubicación regional o multirregional del repositorio. Usa esta marca para ver los repositorios de una ubicación específica. Si has configurado una ubicación predeterminada, puedes omitir esta marca para usarla.

Ver paquetes y versiones desde la consola de Google Cloud o la CLI de gcloud solo está disponible para repositorios estándar y remotos.

En el caso de los repositorios remotos, la lista devuelta debe incluir todas las dependencias directas y transitivas que estén almacenadas en caché en el repositorio.

Mostrar archivos

Modos de repositorio: estándar y remoto

Puedes enumerar los archivos de un repositorio, los archivos de todas las versiones de un paquete especificado o los archivos de una versión concreta de un paquete.

En todos los comandos siguientes, puedes definir un número máximo de archivos que se devuelvan añadiendo la marca --limit al comando.

Para enumerar todos los archivos del proyecto, el repositorio y la ubicación predeterminados cuando se configuran los valores predeterminados, haz lo siguiente:

gcloud artifacts files list

Para enumerar los archivos de un proyecto, un repositorio y una ubicación específicos, ejecuta el siguiente comando:

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

Para enumerar los archivos de todas las versiones de un paquete específico, haz lo siguiente:

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

Para enumerar los archivos de una versión específica de un paquete, sigue estos pasos:

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

Para enumerar los archivos de una etiqueta específica, sigue estos pasos:

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

Sustituye los siguientes valores:

• LOCATION: la ubicación regional o multirregional del repositorio.
• PROJECT: tu Google Cloud ID de proyecto. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con ámbito de dominio.
• REPOSITORY: el nombre del repositorio en el que se almacena la imagen.
• PACKAGE: el nombre del paquete.
• VERSION: la versión del paquete.
• TAG: la etiqueta asociada al paquete.

Ejemplos

Tenga en cuenta la siguiente información del paquete:

• Proyecto: my-project
• Repositorio: my-repo
• Ubicación del repositorio: us-west1
• Paquete: my-app

El siguiente comando muestra todos los archivos del repositorio my-repo en la ubicación us-west1 del proyecto predeterminado:

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

El siguiente comando muestra los archivos de la versión 1.0 del paquete.

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

El siguiente comando muestra los archivos de la versión del paquete con la etiqueta 1.0-dev:

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

Etiquetar paquetes

Modos de repositorio: estándar

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.

   Abre la página Repositorios.

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.

   Abre la página Repositorios.

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.

   Abre la página Repositorios.

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.

   Abre la página Repositorios.

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

Instalar paquetes

Modos de repositorio: estándar, remoto y virtual

Para instalar un paquete desde el repositorio de paquetes de Node.js, sigue estos pasos:

1. Si usas el asistente de credenciales para autenticarte con un token de acceso, obtén un nuevo token.

2. Usa el comando npm install o yarn add.

   npm

   Para instalar la versión con la etiqueta latest, sigue estos pasos:

   npm install @SCOPE/PACKAGE
   

   Para instalar la versión con una etiqueta diferente, sigue estos pasos:

   npm install @SCOPE/PACKAGE@TAG
   

   Para instalar una versión específica, sigue estos pasos:

   npm install @SCOPE/PACKAGE@VERSION
   

   lana

   Para instalar la versión con la etiqueta latest, sigue estos pasos:

   yarn add @SCOPE/PACKAGE
   

   Para instalar la versión con una etiqueta diferente, sigue estos pasos:

   yarn add @SCOPE/PACKAGE@TAG
   

   Para instalar una versión específica, sigue estos pasos:

   yarn add @SCOPE/PACKAGE@VERSION
   

   Sustituye los siguientes valores:

   • SCOPE es el ámbito asociado al repositorio. Si tu repositorio de paquetes de Node.js no está configurado con un ámbito, omite @SCOPE/ del comando.
   • PACKAGE es el nombre del paquete en el repositorio.
   • TAG es la etiqueta de la versión que quieres instalar.
   • VERSION es el número de versión que quieres instalar.

Cuando especifiques un paquete como dependencia en package.json, asegúrate de incluir el ámbito del repositorio. En el siguiente ejemplo se muestra el ámbito @dev-repo de un paquete llamado my-package.

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

En los repositorios estándar, los paquetes se descargan directamente del repositorio.

En el caso de un repositorio remoto, se descarga una copia en caché del paquete y sus dependencias. Si no existe una copia almacenada en caché, el repositorio remoto descarga el paquete de la fuente upstream y lo almacena en caché antes de proporcionártelo. Para comprobar que el repositorio remoto ha obtenido los paquetes de la fuente de nivel superior, consulta la lista de paquetes del repositorio.

En el caso de un repositorio virtual, Artifact Registry busca el paquete solicitado en los repositorios upstream.

• Los repositorios remotos upstream descargarán y almacenarán en caché el paquete solicitado si no existe una copia en caché. Los repositorios virtuales solo sirven los paquetes solicitados, no los almacenan.
• Si solicita una versión que está disponible en más de un repositorio upstream, Artifact Registry elige un repositorio upstream que se va a usar en función de los ajustes de prioridad configurados para el repositorio virtual.

Por ejemplo, supongamos que tiene un repositorio virtual con los siguientes ajustes de prioridad para los repositorios upstream:

• main-repo: prioridad definida como 100
• secondary-repo1: prioridad establecida en 80.
• secondary-repo2: prioridad establecida en 80.
• test-repo: prioridad establecida en 20.

main-repo tiene el valor de prioridad más alto, por lo que el repositorio virtual siempre lo busca primero.

Tanto secondary-repo1 como secondary-repo2 tienen la prioridad 80. Si un paquete solicitado no está disponible en main-repo, Artifact Registry buscará en estos repositorios. Como ambos tienen el mismo valor de prioridad, Artifact Registry puede elegir servir un paquete de cualquiera de los dos repositorios si la versión está disponible en ambos.

test-repo tiene el valor de prioridad más bajo y servirá un artefacto almacenado si ninguno de los otros repositorios upstream lo tiene.

Eliminar paquetes

Modos de repositorio: estándar y remoto

Puedes eliminar un paquete y todas sus versiones, o bien eliminar una versión específica.

• Una vez que elimines un paquete, no podrás deshacer la acción.
• En el caso de los repositorios remotos, solo se elimina la copia almacenada en caché del paquete. La fuente upstream no se ve afectada. Si eliminas un paquete almacenado en caché, Artifact Registry lo descargará y lo almacenará en caché de nuevo la próxima vez que el repositorio reciba una solicitud para la misma versión del paquete.

Una vez que se ha publicado una versión de un paquete, no se puede volver a publicar un paquete con la misma combinación de nombre y versión, aunque se elimine la versión. Se trata de una restricción de npm para asegurarse de que el contenido de una versión publicada de un paquete sea siempre el mismo.

Si quieres animar a los usuarios a instalar una versión actualizada de un paquete, usa el comando npm deprecate para marcar la versión antigua del paquete como obsoleta. Cuando un usuario intenta instalar el paquete obsoleto, Artifact Registry devuelve una advertencia de obsolescencia.

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

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

   Abre la página Repositorios.

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Select the package that you want to delete.

4. Click DELETE.

5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

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

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

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

   Abre la página Repositorios.

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Click a package to view versions of that package.

4. Select versions that you want to delete.

5. Click DELETE.

6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

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

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

Siguientes pasos

• Más información sobre cómo gestionar paquetes de Maven
• Consulta cómo gestionar imágenes de contenedor.
• Descargar archivos concretos de un paquete