Publicar paquetes

  • 5 minutos

La publicación de paquetes en Paquetes de GitHub permite compartir bibliotecas de código, imágenes de contenedor y dependencias con el equipo o el público. Paquetes de GitHub usa comandos de herramientas de paquetes nativos, por lo que puede publicar paquetes con las mismas herramientas y flujos de trabajo que ya conoce.

Descripción de los registros de paquetes

Paquetes de GitHub admite varios ecosistemas de paquetes, cada uno con su propio formato y herramientas de cliente:

Lenguaje Formato del paquete Cliente del paquete
JavaScript package.json npm
Ruby Gemfile gem
Java pom.xml mvn
Java build.gradle o build.gradle.kts gradle
.NET nupkg CLI de dotnet
N/D Dockerfile Docker

Documentación y metadatos del paquete

Al crear un paquete, puede proporcionar metadatos enriquecidos en la página del paquete:

  • Descripción: Explicación clara de lo que hace el paquete
  • Instrucciones de instalación: Guía paso a paso para los consumidores
  • Ejemplos de uso: Ejemplos de código que muestran casos de uso comunes
  • Dependencias: Paquetes y versiones necesarios
  • Información de licencia: Términos legales para el uso del paquete
  • Historial de versiones: Registro de cambios de actualizaciones y correcciones

Una buena documentación ayuda a los usuarios que consumen el paquete a comprender cómo usarlo y sus propósitos. Considere la posibilidad de incluir:

  • Guía de inicio rápido: Poner a los usuarios en funcionamiento rápidamente
  • Referencia de API: Documentación detallada de las interfaces públicas
  • Sugerencias para solucionar problemas: Problemas comunes y soluciones
  • Guías de migración: Actualización entre versiones principales

Advertencias de seguridad

Si una nueva versión del paquete corrige una vulnerabilidad de seguridad, puede publicar un aviso de seguridad en el repositorio. Esto notifica a los usuarios de la vulnerabilidad y proporciona instrucciones sobre cómo actualizar a versiones seguras.

Sugerencia

Puede conectar un repositorio a más de un paquete. Por ejemplo, un monorepo podría publicar varios paquetes npm o una imagen de Docker junto con un paquete NuGet. Asegúrese de que el archivo léame y la descripción proporcionan información sobre cada paquete para evitar confusión.

Flujo de trabajo de publicación

Para publicar un paquete en Paquetes de GitHub, siga estos tres pasos principales:

1. Creación de un token de acceso personal (PAT)

La autenticación es necesaria para publicar paquetes. Cree un token de acceso personal con los ámbitos adecuados:

  • write:packages: necesario para publicar paquetes
  • read:packages: necesario para descargar paquetes
  • delete:packages: necesario para eliminar las versiones del paquete
  • repo: Necesario para paquetes con ámbito de repositorio privado.

Para crear un PAT:

  1. Vaya a Configuración → Configuración del desarrollador → tokens de acceso personal
  2. Haga clic en Generar nuevo token (clásico)
  3. Seleccione los ámbitos necesarios en función de sus necesidades.
  4. Establecer una fecha de expiración (más corta es más segura)
  5. Copie el token inmediatamente (no lo volverá a ver)

Para obtener instrucciones detalladas, consulte Creación de un token de acceso personal.

2. Autenticación en paquetes de GitHub

Usa tu PAT para autenticarte con el cliente de paquetes. Los métodos de autenticación varían según el tipo de paquete, pero normalmente implican la configuración de un archivo de credenciales o una variable de entorno.

Procedimientos recomendados de seguridad:

  • Nunca comprometa tokens en el código fuente: Use variables de entorno o almacenamiento seguro de credenciales
  • Use ámbitos mínimos requeridos: No conceda más permisos de los necesarios
  • Rotar tokens con regularidad: Establecer fechas de expiración y renovar periódicamente
  • Uso de secretos de organización: Para Acciones de GitHub, almacene PAT como secretos cifrados.

3. Publicar el paquete

Usa los comandos nativos del cliente del paquete para publicar. El comando específico depende del tipo de paquete (npm, NuGet, Maven, Docker, etc.).

Lista de comprobación de publicación:

  • El número de versión sigue el control de versionamiento Semántico (MAYOR.MENOR.REVISIÓN)
  • Los metadatos del paquete están completos (descripción, autor, licencia)
  • Las dependencias se especifican correctamente con restricciones de versión
  • Se incluye documentación (LÉAME, referencia de la API)
  • Las pruebas se superan correctamente antes de publicarlas
  • El nombre del paquete no entra en conflicto con los paquetes existentes

Para obtener instrucciones específicas del Registro, consulte Trabajar con un registro de paquetes de GitHub.

Publicación de paquetes NuGet

Los paquetes NuGet se usan para las aplicaciones y bibliotecas de .NET. Puede publicarlos mediante la CLI de dotnet.

Configurar la autenticación

Cree un archivo nuget.config en el directorio del proyecto para especificar paquetes de GitHub como origen:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://nuget.pkg.github.com/OWNER/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

Parámetros de configuración:

  • DUEÑO: Nombre de usuario o organización de GitHub que posee el repositorio
  • NOMBRE DE USUARIO: Nombre de usuario de GitHub
  • TOKEN: Su token de acceso personal con ámbito write:packages

Nota

Reemplace USERNAME por el nombre de su cuenta personal en GitHub, TOKEN por su PAT y OWNER por el nombre de la cuenta de usuario u organización que posee el repositorio del proyecto.

Publicación del paquete

Puede publicar con dos métodos:

Método 1: Uso del archivo nuget.config

dotnet nuget push "bin/Release/OctocatApp.1.0.0.nupkg" --source "github"

Método 2: Uso de la opción --api-key

dotnet nuget push "bin/Release/OctocatApp.1.0.0.nupkg" --api-key YOUR_GITHUB_PAT --source "github"

Procedimientos recomendados para la publicación de NuGet:

  • Usar la configuración de lanzamiento: Compilar con dotnet pack -c Release para paquetes optimizados
  • Incluir símbolos: Publicar paquetes de símbolos (.snupkg) para soporte de depuración
  • Versión automática: Uso de las propiedades de MSBuild para versionar desde etiquetas de Git
  • Validar paquete: Prueba de la instalación del paquete antes de publicar
  • Documentación de cambios importantes: actualice las notas de la versión para los cambios de la versión principal

Publicación de paquetes npm

Los paquetes npm se usan para aplicaciones de JavaScript y Node.js. Puede publicarlos mediante la CLI de npm.

Configurar la autenticación

Tiene dos opciones de autenticación:

Opción 1: Editar archivo ~/.npmrc

Agregue su PAT al archivo .npmrc por usuario :

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

Cree un nuevo archivo ~/.npmrc si no existe uno. Este método almacena las credenciales globalmente para todos los proyectos.

Opción 2: Iniciar sesión a través de la línea de comandos

Use el comando npm login para la autenticación interactiva:

$ npm login --scope=@OWNER --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

Parámetros de autenticación:

  • NOMBRE DE USUARIO: Nombre de usuario de GitHub
  • TOKEN: Su token de acceso personal con ámbito write:packages
  • PUBLIC-EMAIL-ADDRESS: Su dirección de correo electrónico (pública o privada)
  • DUEÑO: Nombre de usuario u organización de GitHub para paquetes con ámbito de aplicación

Nota

Reemplace USERNAME por su nombre de usuario de GitHub, TOKEN por su PAT y PUBLIC-EMAIL-ADDRESS por su dirección de correo electrónico.

Configuración de package.json

Asegúrese de que package.json incluye el registro y el alcance correctos.

{
  "name": "@OWNER/package-name",
  "version": "1.0.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/OWNER/REPOSITORY.git"
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

Publicación del paquete

Use el comando npm publish estándar:

npm publish

Procedimientos recomendados para la publicación de npm:

  • Utiliza paquetes con ámbito: Añade un prefijo con @owner/ para evitar conflictos de nombres
  • Prueba antes de publicar: Ejecutar npm pack y probar el archivo .tgz localmente
  • Use .npmignore: Excluir archivos innecesarios para reducir el tamaño del paquete
  • Versión con npm: Uso npm version patch/minor/major para actualizar versiones
  • Publicar desde CI/CD: Automatización de la publicación con Acciones de GitHub

Visualización de paquetes publicados

Después de publicar un paquete, puede verlo en GitHub:

  1. Vaya al repositorio.
  2. Haga clic en Paquetes en la barra lateral.
  3. Seleccione el paquete para ver los detalles, las versiones y las estadísticas de descarga.

Para obtener un ejemplo, consulte Codertocat/hello-world-npm.

Para obtener instrucciones completas, consulte Trabajar con el registro de npm.

Automatización de la publicación de paquetes con Acciones de GitHub

Puede automatizar la publicación de paquetes mediante flujos de trabajo de Acciones de GitHub . Esto garantiza que los paquetes se publiquen automáticamente cuando cambia el código.

Ejemplo de flujo de trabajo para npm

name: Publish Package

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "18"
          registry-url: "https://npm.pkg.github.com"
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Flujo de trabajo de ejemplo para NuGet

name: Publish Package

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: "8.0.x"
      - run: dotnet pack -c Release
      - run: dotnet nuget push "**/*.nupkg" --source github --api-key ${{ secrets.GITHUB_TOKEN }}

Ventajas de la publicación automatizada:

  • Consistencia: Cada versión crea automáticamente un paquete
  • Velocidad: No se requieren pasos manuales para publicar
  • Trazabilidad: Las versiones del paquete coinciden con etiquetas de Git
  • Puertas de calidad: Ejecución de pruebas antes de publicar
  • Seguridad: Usar el GITHUB_TOKEN integrado en lugar de PATs

Recursos adicionales

Para más información, consulte: