Instalación de un paquete

  • 5 minutos

La instalación de paquetes desde Paquetes de GitHub permite consumir bibliotecas, dependencias e imágenes de contenedor hospedadas en GitHub. Puede instalar cualquier paquete que tenga permiso para verlo y usarlo como dependencia en el proyecto.

Detección de paquetes

Paquetes de GitHub proporciona varias maneras de detectar paquetes:

Opciones de búsqueda

  • Búsqueda global: Búsqueda en todos los paquetes públicos en GitHub
  • Búsqueda de la organización: Búsqueda de paquetes dentro de una organización específica
  • Búsqueda del repositorio: Examinar paquetes publicados desde un repositorio
  • Filtro de tipo de paquete: Filtre por npm, NuGet, Maven, Docker, etc.

Para obtener más información, consulte Búsqueda de paquetes.

Información del paquete

Cuando encuentre un paquete, la página del paquete proporciona información esencial:

  • Descripción: Qué hace el paquete y su finalidad
  • Instrucciones de instalación: Cómo agregar el paquete al proyecto
  • Historial de versiones: Versiones disponibles y notas de la versión
  • Dependencias: Paquetes necesarios y restricciones de versión
  • Ejemplos de uso: Ejemplos de código que muestran escenarios comunes
  • Licencia: Términos legales para usar el paquete
  • Descargar estadísticas: Cuántas veces se ha instalado el paquete

Procedimiento recomendado: Lea siempre las instrucciones de instalación y descripción del paquete antes de instalar para comprender los requisitos, los cambios importantes y la compatibilidad.

Flujo de trabajo de instalación

La instalación de un paquete sigue un proceso coherente de dos pasos independientemente del tipo de paquete:

1. Autenticación en paquetes de GitHub

Configure el cliente de paquetes para autenticarse con GitHub Packages usando un token de acceso personal (PAT) con el ámbito read:packages.

Requisitos de autenticación:

  • Paquetes públicos: La autenticación es necesaria incluso para paquetes públicos
  • Paquetes privados: Requiere PAT con acceso adecuado al repositorio
  • Paquetes de organización: Puede requerir la pertenencia a la organización.
  • Paquetes internos: Solo está disponible en organizaciones de GitHub Enterprise

2. Instalar el paquete

Use los comandos de instalación nativa del cliente del paquete (npm install, dotnet add package, mvn install, etc.) para agregar el paquete al proyecto.

Lista de comprobación de instalación:

  • Compruebe que el nombre y la versión del paquete son correctos.
  • Comprobación de la compatibilidad con la versión del marco del proyecto
  • Revise el árbol de dependencias por conflictos
  • Probar la funcionalidad del paquete después de la instalación
  • Actualización de la documentación para reflejar la nueva dependencia

Instalación de paquetes NuGet

Los paquetes NuGet se pueden instalar mediante Visual Studio o la CLI de dotnet.

Método 1: Visual Studio

Visual Studio proporciona una interfaz gráfica para administrar paquetes NuGet:

  1. Abra el Administrador de paquetes NuGet:

    • Expandir Solución → Proyecto
    • Haga clic con el botón derecho en Dependencias.
    • Seleccione Administrar paquetes NuGet...

    captura de pantalla de la opción de Visual Studio para administrar paquetes NuGet.

  2. Examinar e instalar:

    • Haga clic en la pestaña Examinar.
    • Busque el nombre del paquete.
    • Seleccione la versión que desee.
    • Haga clic en Instalar

    Captura de pantalla de cómo administrar paquetes NuGet, instalar y actualizar desde Visual Studio.

Puede examinar, instalar y actualizar las dependencias de varios registros simultáneamente. Para obtener más información, vea Crear y quitar dependencias del proyecto.

Método 2: Editar .csproj directamente

Puede agregar referencias de paquete directamente al archivo del proyecto:

Paso 1: Autenticación en paquetes de GitHub

Cree o actualice el archivo nuget.config (consulte la sección Publicación para obtener más información sobre la autenticación).

Paso 2: Agregar PackageReference

Agregue un ItemGroup con packageReference en el archivo .csproj :

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net8.0</TargetFramework>
        <PackageId>OctocatApp</PackageId>
        <Version>1.0.0</Version>
        <Authors>Octocat</Authors>
        <Company>GitHub</Company>
        <PackageDescription>This package adds an Octocat!</PackageDescription>
        <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="OctokittenApp" Version="12.0.2" />
    </ItemGroup>
</Project>

Nota

Reemplace OctokittenApp por el nombre del paquete y 12.0.2 por la versión que desea usar.

Paso 3: Restaurar paquetes

Instale los paquetes mediante el comando restore :

dotnet restore

Método 3: Uso de la CLI de dotnet

Puede instalar paquetes mediante el comando dotnet add :

dotnet add package OctokittenApp --version 12.0.2 --source github

Procedimientos recomendados para la instalación de NuGet:

  • Fijar versiones: Especificar versiones exactas para compilaciones reproducibles
  • Use la administración central de paquetes: Consolidación de versiones en Directory.Packages.props
  • Revise las vulnerabilidades: Comprobación de avisos de seguridad antes de instalar
  • Compatibilidad de pruebas: Asegúrese de que el paquete funciona con la plataforma de destino

Instalación de paquetes de npm

Los paquetes npm requieren configurar un archivo .npmrc para especificar paquetes de GitHub como registro.

Configuración del archivo .npmrc

Paso 1: Autenticación en paquetes de GitHub

Cree o actualice el archivo ~/.npmrc con el token de autenticación (consulte la sección Publicación para obtener más información sobre la autenticación).

Paso 2: Creación del proyecto .npmrc

En el mismo directorio que el archivo de package.json, cree o edite un archivo .npmrc :

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

Nota

Reemplace OWNER por el nombre de la cuenta de usuario u organización que posee el paquete.

Paso 3: Confirmar .npmrc en el repositorio

Agregue el archivo .npmrc al repositorio para que todos los miembros del equipo usen la misma configuración. Consulte Adición de un archivo a un repositorio.

Agregar dependencia a package.json

Configure package.json para incluir el paquete como una dependencia:

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

Especificación de dependencia:

  • Versión exacta:"1.0.0" instala una versión específica
  • Intervalo de cursor de inserción:"^1.0.0" instala actualizaciones menores o de revisión compatibles
  • Rango de tilde:"~1.0.0" instala solo actualizaciones de revisiones compatibles
  • Último:"latest" instala la versión más reciente (no recomendada para producción)

Instalar el paquete

Ejecute el comando npm install :

npm install

O bien, instale un paquete específico:

npm install @octo-org/octo-app

Varias organizaciones

Si necesita instalar paquetes de varias organizaciones, agregue líneas adicionales al archivo .npmrc :

@first-org:registry=https://npm.pkg.github.com
@second-org:registry=https://npm.pkg.github.com
@third-org:registry=https://npm.pkg.github.com

Procedimientos recomendados para la instalación de npm:

  • Use package-lock.json: Confirmar el archivo de bloqueo para asegurar instalaciones consistentes en todos los entornos
  • Dependencias de auditoría: Ejecutar npm audit para comprobar si hay vulnerabilidades
  • Use npm ci: En las canalizaciones de CI/CD, use npm ci para instalaciones más rápidas y confiables.
  • Restricciones de versión: Uso de intervalos de versiones semánticos para equilibrar la estabilidad y las actualizaciones
  • Registro privado primero: Configurar los ámbitos para verificar los paquetes de GitHub antes del registro público de npm

Instalación en canalizaciones de CI/CD

Puede instalar paquetes en flujos de trabajo de Acciones de GitHub con los mismos métodos:

npm en Acciones de GitHub

- uses: actions/setup-node@v4
  with:
    node-version: "18"
    registry-url: "https://npm.pkg.github.com"
    scope: "@OWNER"
- run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

NuGet en Acciones de GitHub

- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: "8.0.x"
    source-url: https://nuget.pkg.github.com/OWNER/index.json
  env:
    NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: dotnet restore

Ventajas de GITHUB_TOKEN:

  • No se requiere PAT: Disponible automáticamente en flujos de trabajo
  • Permisos con ámbito: limitado al acceso al repositorio del flujo de trabajo
  • Rotación automática: El token se vuelve a generar para cada ejecución de flujo de trabajo
  • Seguro: Nunca se expone en registros ni artefactos

Solución de problemas de instalación

Problemas y soluciones comunes:

Problema Causa Solution
401 No autorizado PAT faltante o no es válido Verifique que el token tenga read:packages alcance
404 No encontrado El nombre del paquete o la dirección URL del Registro son incorrectos Verifique que el paquete existe y que el propietario sea el correcto
403 Prohibido Sin permiso para acceder al paquete Solicitar acceso o comprobar la pertenencia a la organización
No se encontró la versión La versión solicitada no existe Comprobación de las versiones disponibles en la página del paquete
Conflictos de dependencias Versiones de paquetes incompatibles Actualizar otras dependencias o usar resoluciones

Recursos adicionales

Para obtener más información, consulte: