Trabajar con el registro de NuGet

Es posible configurar la interfaz de línea de comandos (CLI) dotnet para publicar paquetes NuGet en GitHub Packages y utilizar paquetes almacenados en GitHub Packages como dependencias de un proyecto .NET.

En este artículo

Nota:

Este tipo de paquete podría no estar disponible para tu instancia, ya que los administradores del sitio pueden habilitar o inhabilitar cada tipo de paquete compatible. Para más información, consulta Configurar la compatibilidad del ecosistema de paquetes para tu empresa.

Autenticar a GitHub Packages

Nota:

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

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

Puedes utilizar un personal access token (classic) para autenticarte en el 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 alcance read:packages para instalar los paquetes asociados con otros repositorios privados (GITHUB_TOKEN puede utilizarse si el repositorio tiene acceso de lectura al paquete. Consulta Configurar la visibilidad y el control de accesos de un paquete).

Autenticación en un flujo de trabajo de 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.HOSTNAME/NAMESPACE/index.json"

Reemplaza NAMESPACE por el nombre de la cuenta personal u organización que posee el repositorio donde se hospedan los paquetes.

Reemplace USERNAME con el nombre de usuario que se usará al conectarse a un origen autenticado.

Para más información sobre el uso de GITHUB_TOKEN en flujos de trabajo de GitHub Actions, consulta Uso de GITHUB_TOKEN para la autenticación en flujos de trabajo.

Autenticación con un personal access token

Nota:

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

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

Puedes utilizar un personal access token (classic) para autenticarte en el 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 alcance read:packages para instalar los paquetes asociados con otros repositorios privados (GITHUB_TOKEN puede utilizarse si el repositorio tiene acceso de lectura al paquete. Consulta Configurar la visibilidad y el control de accesos de un paquete).

Debes utilizar un personal access token (classic) con los ámbitos adecuados para publicar e instalar paquetes en GitHub Packages. Para más información, consulta 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 su cuenta personal en GitHub.

  •           `TOKEN` por su personal access token (classic).

  •           `NAMESPACE` por el nombre de la cuenta personal u organización que posee el repositorio donde se hospedan los paquetes.

  •           `HOSTNAME` por el nombre de host de tu instancia de GitHub Enterprise Server.

Si en la instancia se ha habilitado el aislamiento de subdominios:

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

Si en la instancia se ha deshabilitado el aislamiento de subdominios:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://HOSTNAME/_registry/nuget/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 en GitHub Packages autenticándose con un archivo nuget.config, utilizando la opción de línea de comandos --api-key con su GitHub personal access token (classic) o utilizando el comando que se puede ejecutar directamente desde la línea de comandos utilizando la interfaz de línea de comandos (CLI) dotnet.

Reemplace OWNER por su nombre de usuario o el de su empresa, y YOUR_GITHUB_PAT por su personal access token.

dotnet nuget add source --username OWNER --password YOUR_GITHUB_PAT --store-password-in-clear-text --name github "https://nuget.HOSTNAME/OWNER/index.json"

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 usarlo para su cuenta en GitHub, consulte Administración de tokens de acceso personal.

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

    dotnet new console --name PROJECT_NAME

  2. Empaqueta 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 su 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 más información, consulta Visualizar paquetes.

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

Al publicar, 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, consulta Creación y publicación de un paquete en la documentación de Microsoft.

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

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

    dotnet new console --name PROJECT_NAME

  3. Agregue la información específica de su proyecto al archivo del proyecto, que termina en .csproj. Asegúrese de reemplazar:

    •      `1.0.0` con el número de versión del paquete.

    •      `OWNER` con el nombre de la cuenta personal u organización que posee el repositorio al que deseas publicar tu paquete.

    •      `REPOSITORY` con el nombre del repositorio al que quiere conectar el paquete.

    •           `HOSTNAME` por el nombre de host de tu instancia de GitHub Enterprise Server.

    <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://HOSTNAME/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

</Project>

  4. Empaqueta 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 project 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 más información, consulta Visualizar paquetes.

Publicar múltiples paquetes en el mismo repositorio

Para conectar varios paquetes al mismo repositorio, use la misma dirección URL del repositorio GitHub en los campos RepositoryURL de todos los archivos .csproj de proyecto. GitHub compara con el repositorio basándose en 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://HOSTNAME/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://HOSTNAME/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 la project, consulte Working with NuGet packages en la documentación de Microsoft.

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

  2. Para usar un paquete, agregue ItemGroup y configure el campo PackageReference en el archivo .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://HOSTNAME/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

Es posible que el paquete de NuGet no se inserte si RepositoryUrl en .csproj no está establecido en el repositorio previsto.

Si usas un archivo nuspec, asegúrate de que tiene un elemento repository con los atributos type y url necesarios.

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.

Errores intermitentes 403 al restaurar paquetes públicos

Si está usando GitHub Packages junto con nuget.org y experimenta errores intermitentes 403 Forbidden al restaurar paquetes públicos estándar (como Microsoft.Extensions.*), esto puede deberse a que NuGet consulta todas las fuentes de paquetes configuradas para cada paquete. Si se produce temporalmente un error de autenticación GitHub Packages, puede bloquear toda la restauración, incluso para los paquetes que no existen en GitHub Packages.

Para evitar esto, use la asignación de origen del paquete NuGet para enrutar paquetes a orígenes específicos.

Reemplazar:

  •           `NAMESPACE` por el nombre de la cuenta personal u organización que posee su repositorio NuGet de GitHub Packages NuGet feed.

  •           `PACKAGE-ID-PREFIX` por el prefijo ID del paquete NuGet que usa para los paquetes alojados en GitHub Packages. Si usa varios prefijos, agregue entradas adicionales `<package>` para cada prefijo.

  •           `HOSTNAME` por el nombre de host de tu instancia de GitHub Enterprise Server.

Si en la instancia se ha habilitado el aislamiento de subdominios:

<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="github" value="https://nuget.HOSTNAME/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceMapping>
        <packageSource key="nuget.org">
            <package pattern="*" />
        </packageSource>
        <packageSource key="github">
            <package pattern="PACKAGE-ID-PREFIX.*" />
        </packageSource>
    </packageSourceMapping>
</configuration>

Si en la instancia se ha deshabilitado el aislamiento de subdominios:

<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="github" value="https://HOSTNAME/_registry/nuget/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceMapping>
        <packageSource key="nuget.org">
            <package pattern="*" />
        </packageSource>
        <packageSource key="github">
            <package pattern="PACKAGE-ID-PREFIX.*" />
        </packageSource>
    </packageSourceMapping>
</configuration>

NuGet usa el patrón de coincidencia más específico, por lo que los paquetes que coinciden exactamente PACKAGE-ID-PREFIX.* se obtienen solo de GitHub Packages, mientras que todos los demás paquetes se obtienen de nuget.org. Esto también ayuda a evitar ataques de confusión de dependencias asegurándose de que los paquetes privados solo puedan provenir de la fuente GitHub Packages.

Información adicional

  •         [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package)