Skip to main content

Trabajar con el registro de NuGet

Puedes configurar la interfaz de línea de comando (CLI) dotnet para publicar paquetes NuGet en GitHub Packages y usar paquetes almacenados en GitHub Packages como dependencias en un proyecto de .NET.

¿Quién puede utilizar esta característica?

GitHub Packages está disponible con GitHub Free, GitHub Pro, GitHub Free para organizaciones, GitHub Team, GitHub Enterprise Cloud y GitHub Enterprise Server 3.0 o superior
GitHub Packages no está disponible para repositorios privados que pertenezcan a cuentas que utilicen planes tradicionales por repositorio. Además, las cuentas que usan planes heredados por repositorio no pueden acceder a los registros que admiten permisos granulares, ya que estas cuentas se facturan por repositorio. Para la lista de registros que admiten permisos granulares, consulta "Acerca de los permisos para los Paquetes de GitHub". Para más información, consulta "Planes de GitHub".

Autenticar a GitHub Packages

GitHub Packages solo admite la autenticación mediante un personal access token (classic). Para obtener más información, vea «Administración de tokens de acceso personal».

Necesitas un token de acceso para publicar, instalar y eliminar paquetes privados, internos y públicos.

Puedes usar un personal access token (classic) para autenticarte en GitHub Packages o en la API de GitHub. Cuando creas un personal access token (classic), puedes asignar al token diferentes ámbitos en función de tus necesidades. Para más información sobre los ámbitos relacionados con paquetes para un personal access token (classic), consulta "Acerca de los permisos para los Paquetes de GitHub".

Para autenticarte en un registro del GitHub Packages dentro de un flujo de trabajo de GitHub Actions, puedes utilizar:

  • GITHUB_TOKEN para publicar los paquetes asociados con el repositorio del flujo de trabajo.
  • Un personal access token (classic) con, al menos, ámbito de read:packages para instalar los paquetes asociados con otros repositorios privados (a los cuales no puede acceder GITHUB_TOKEN).

Autenticación en un flujo de trabajo de GitHub Actions

Este registro admite permisos granulares. Para los registros que admiten permisos detallados, si en el flujo de trabajo de GitHub Actions se usa un personal access token para autenticarse en un registro, se recomienda encarecidamente actualizar el flujo de trabajo para usar GITHUB_TOKEN. Para obtener orientación sobre la actualización de tus flujos de trabajo que se autentican en un registro con un personal access token, consulta "Publicar e instalar un paquete con GitHub Actions".

Nota: La capacidad de los flujos de trabajo de GitHub Actions para eliminar y restaurar paquetes mediante la API de REST está actualmente en versión beta pública y está sujeta a cambios.

Puedes usar un GITHUB_TOKEN en un flujo de trabajo de GitHub Actions para eliminar o restaurar un paquete mediante la API de REST, si el token tiene el permiso admin para el paquete. A los repositorios que publican paquetes mediante un flujo de trabajo y a los repositorios que se han conectado explícitamente a los paquetes se les concede automáticamente el permiso admin para los paquetes del repositorio.

Para obtener más información sobre GITHUB_TOKEN, consulta "Autenticación automática de tokens". Para obtener más información sobre los procedimientos recomendados al usar un registro en acciones, consulta "Fortalecimiento de seguridad para GitHub Actions".

Utilice el siguiente comando para autenticarse en GitHub Packages en un flujo de trabajo de GitHub Actions utilizando GITHUB_TOKEN en vez de codificar de forma rígida un personal access token en un archivo nuget.config en el repositorio:

dotnet nuget add source --username USERNAME --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github "https://nuget.pkg.github.com/NAMESPACE/index.json"

Reemplaza NAMESPACE por el nombre de la cuenta personal u organización a la que se limitan los paquetes.

También puedes optar por conceder permisos de acceso a paquetes de forma independiente para GitHub Codespaces y GitHub Actions. Para obtener más información, vea «Configurar la visibilidad y el control de accesos de un paquete» y «Configurar la visibilidad y el control de accesos de un paquete».

Autenticación con un personal access token

GitHub Packages solo admite la autenticación mediante un personal access token (classic). Para obtener más información, vea «Administración de tokens de acceso personal».

Necesitas un token de acceso para publicar, instalar y eliminar paquetes privados, internos y públicos.

Puedes usar un personal access token (classic) para autenticarte en GitHub Packages o en la API de GitHub. Cuando creas un personal access token (classic), puedes asignar al token diferentes ámbitos en función de tus necesidades. Para más información sobre los ámbitos relacionados con paquetes para un personal access token (classic), consulta "Acerca de los permisos para los Paquetes de GitHub".

Para autenticarte en un registro del GitHub Packages dentro de un flujo de trabajo de GitHub Actions, puedes utilizar:

  • GITHUB_TOKEN para publicar los paquetes asociados con el repositorio del flujo de trabajo.
  • Un personal access token (classic) con, al menos, ámbito de read:packages para instalar los paquetes asociados con otros repositorios privados (a los cuales no puede acceder GITHUB_TOKEN).

Debes utilizar un personal access token (classic) con los ámbitos adecuados para publicar e instalar paquetes en GitHub Packages. Para obtener más información, vea «Introducción a los paquetes de GitHub».

Para autenticarse en GitHub Packages con la interfaz de la línea de comandos (CLI) dotnet, cree un archivo nuget.config en el directorio del proyecto que especifique que GitHub Packages es el origen en packageSources para el cliente de la CLI dotnet.

Debes reemplazar:

  • USERNAME por el nombre de tu cuenta personal en GitHub.
  • TOKEN por tu personal access token (classic).
  • Reemplace NAMESPACE por el nombre de la cuenta personal u organización a la que se limitan los paquetes.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://nuget.pkg.github.com/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

Publicación de un paquete

Puede publicar un paquete de GitHub Packages si se autentica con un archivo nuget.config o utiliza la opción de línea de comandos --api-key con su personal access token (classic) de GitHub.

El registro de NuGet almacena paquetes en tu cuenta personal o de la organización y te permite asociar los paquetes a un repositorio. Puedes elegir si quieres heredar permisos desde un repositorio o si quieres configurar permisos granulares independientemente de un repositorio.

Cuando publicas un paquete por primera vez, la visibilidad predeterminada es privada. Para cambiar la visibilidad o establecer permisos de acceso, consulta "Configurar la visibilidad y el control de accesos de un paquete". Para obtener más información sobre cómo vincular un paquete publicado con un repositorio, consulta "Conectar un repositorio a un paquete".

Si especificas un elemento RepositoryURL en el archivo nuget.config, el paquete publicado se conectará automáticamente al repositorio especificado. Para obtener más información, vea «Trabajar con el registro de NuGet». Para obtener información sobre cómo vincular un paquete ya publicado a un repositorio, consulta "Conectar un repositorio a un paquete".

Publicación de un paquete utilizando un personal access token de GitHub como clave de API

Si aún no tiene un personal access token para utilizar en su cuenta en GitHub.com, consulte "Administración de tokens de acceso personal."

  1. Cree un nuevo proyecto. Reemplace PROJECT_NAME por el nombre que desea asignar al proyecto.

    dotnet new console --name PROJECT_NAME
    
  2. Empaquetar el proyecto.

    dotnet pack --configuration Release
    
  3. Publica el paquete utilizando tu personal access token como clave de API. Reemplace PROJECT_NAME por el nombre del proyecto, 1.0.0 por el número de versión del paquete y YOUR_GITHUB_PAT por los datos personal access token.

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

Después de que publiques un paquete, puedes verlo en GitHub. Para obtener más información, vea «Visualizar paquetes».

Publicación de un paquete mediante un archivo nuget.config

Al publicar, si estás vinculando el paquete a un repositorio, el OWNER del repositorio especificado en el archivo .csproj debe coincidir con el NAMESPACE que utilizas en el archivo de autenticación denuget.config. Especifique o incremente el número de versión en el archivo .csproj y, a continuación, use el comando dotnet pack para crear un archivo .nuspec para esa versión. Para obtener más información sobre cómo crear el paquete, consulte "Creación y publicación de un paquete" en la documentación de Microsoft.

Nota: Si publicas un paquete vinculado a un repositorio, el paquete hereda automáticamente los permisos de acceso del repositorio vinculado y los flujos de trabajo de GitHub Actions en el repositorio vinculado automáticamente obtienen acceso al paquete, a menos que la organización haya deshabilitado la herencia automática de los permisos de acceso. Para obtener más información, vea «Configurar la visibilidad y el control de accesos de un paquete».

  1. Autentícate en GitHub Packages. Para obtener más información, vea "Autenticación en GitHub Packages".

  2. Cree un nuevo proyecto. Reemplace PROJECT_NAME por el nombre que desea asignar al proyecto.

    dotnet new console --name PROJECT_NAME
    
  3. Agregue la información específica del proyecto en su archivo, que finaliza en .csproj. Asegúrese de reemplazar:

    • 1.0.0 con el número de versión del paquete.
    • OWNER por el nombre de la cuenta personal u organización que posee el repositorio al que deseas vincular el paquete.
    • REPOSITORY con el nombre del repositorio al que quiere conectar el paquete.
    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <PackageId>PROJECT_NAME</PackageId>
        <Version>1.0.0</Version>
        <Authors>AUTHORS</Authors>
        <Company>COMPANY_NAME</Company>
        <PackageDescription>PACKAGE_DESCRIPTION</PackageDescription>
        <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
      </PropertyGroup>
    
    </Project>
    
  4. Empaquetar el proyecto.

    dotnet pack --configuration Release
    
  5. Publique el paquete con el key que especificó en el archivo nuget.config. Reemplace PROJECT_NAME por el nombre del proyecto y reemplace 1.0.0 por el número de versión del paquete.

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

Después de que publiques un paquete, puedes verlo en GitHub. Para obtener más información, vea «Visualizar paquetes».

Publicar múltiples paquetes en el mismo repositorio

Para conectar varios paquetes al mismo repositorio, utilice la misma dirección URL del repositorio GitHub en los campos RepositoryURL de todos los archivos de proyecto .csproj. GitHub coincide con el repositorio en base a ese campo.

En el ejemplo siguiente se publican los proyectos MY_APP y MY_OTHER_APP en el mismo repositorio:

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds a singing Octocat!</PackageDescription>
    <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_OTHER_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds a dancing Octocat!</PackageDescription>
    <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

Instalación de un paquete

El uso de paquetes de GitHub en el proyecto es similar al uso de paquetes de nuget.org. Agregue las dependencias del paquete al archivo .csproj y especifique el nombre y la versión del paquete. Para obtener más información sobre el uso de un archivo .csproj en el proyecto, consulte "Trabajar con paquetes de NuGet" en la documentación de Microsoft.

  1. Autentícate en GitHub Packages. Para obtener más información, vea "Autenticación en GitHub Packages".

  2. Para usar un paquete, agrega ItemGroup y configura el campo PackageReference en el archivo del proyecto .csproj. Reemplace el valor PACKAGE_NAME de Include="PACKAGE_NAME" por la dependencia de su paquete, y sustituya el valor X.X.X de Version="X.X.X" por la versión del paquete que desea utilizar:

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <PackageId>My-app</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="PACKAGE_NAME" Version="X.X.X" />
      </ItemGroup>
    
    </Project>
    
  3. Instale los paquetes con el comando restore.

    dotnet restore
    

Solución de problemas

Si usas un GITHUB_TOKEN para autenticarte en un registro GitHub Packages dentro de un flujo de trabajo de GitHub Actions, el token no puede acceder a paquetes privados basados en repositorios en un repositorio distinto del lugar en el que se ejecuta el flujo de trabajo. Para acceder a los paquetes asociados a otros repositorios, genera un personal access token (classic) con el ámbito read:packages y pasa este token como secreto.

Información adicional