Utilisation du registre NuGet

URL du registre NuGet

Si vous accédez à GitHub sur GitHub.com, vous publierez des paquets sur https://nuget.pkg.github.com. Les exemples de cet article utilisent cette URL.

Si vous accédez à GitHub depuis un autre domaine, par exemple octocorp.ghe.com, remplacez « https://nuget.pkg.github.com » par https://nuget.SUBDOMAIN.ghe.com, où SUBDOMAIN est le sous-domaine unique de votre entreprise.

Authentification à GitHub Packages

Vous avez besoin d’un jeton d’accès pour publier, installer et supprimer des packages privés, internes et publics.

Vous pouvez utiliser un personal access token (classic) pour vous authentifier auprès de GitHub Packages ou de l’API GitHub. Quand vous créez un personal access token (classic), vous pouvez l’attribuer à différentes étendues selon vos besoins. Pour plus d’informations sur les étendues liées aux packages pour un personal access token (classic), consultez À propos des autorisations pour les packages GitHub.

Pour vous authentifier sur un registre GitHub Packages dans un workflow GitHub Actions, vous pouvez utiliser :

• GITHUB_TOKEN pour publier des packages associés au dépôt du workflow.
• Un personal access token (classic) avec au moins read:packages la possibilité d'installer des paquets associés à d'autres référentiels privés (GITHUB_TOKEN peut être utilisé si le référentiel a un accès en lecture au paquet. Consultez Configuration du contrôle d’accès et de la visibilité d’un package.

Authentification dans un GitHub Actions flux de travail

Ce registre prend en charge les autorisations granulaires. Pour les registres prenant en charge les autorisations granulaires, si votre workflow GitHub Actions utilise un personal access token pour s’authentifier auprès d’un registre, nous vous recommandons vivement de mettre à jour votre workflow pour utiliser GITHUB_TOKEN. Pour obtenir des conseils sur la mise à jour de vos flux de travail qui s’authentifient auprès d’un registre avec un personal access token, consultez Publication et installation d’un package avec GitHub Actions.

Vous pouvez utiliser un GITHUB_TOKEN dans un workflow GitHub Actions pour supprimer ou restaurer un package via l’API REST si le jeton dispose de l’autorisation admin sur le package. Les référentiels qui publient des packages à l’aide d’un workflow et les référentiels que vous avez explicitement connectés à des packages se voient automatiquement accorder l’autorisation admin aux packages dans le référentiel.

Pour plus d’informations sur GITHUB_TOKEN, consultez Utiliser GITHUB_TOKEN pour l’authentification dans les flux de travail. Pour plus d’informations sur les bonnes pratiques lors de l’utilisation d’un registre dans des actions, consultez Informations de référence sur l’utilisation sécurisée.

Utilisez la commande suivante pour vous authentifier auprès de GitHub Packages dans un flux de travail GitHub Actions à l’aide de GITHUB_TOKEN au lieu d’encoder en dur un personal access token dans un fichier nuget.config du référentiel :

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"

Remplacez NAMESPACE par le nom du compte personnel ou de l’organisation auquel vos packages sont limités.

Remplacez USERNAME par le nom d’utilisateur à utiliser lors de la connexion à une source authentifiée.

Vous pouvez également choisir d’accorder des autorisations d’accès aux packages indépendamment pour GitHub Codespaces et GitHub Actions. Pour plus d’informations, consultez « Configuration du contrôle d’accès et de la visibilité d’un package » et « Configuration du contrôle d’accès et de la visibilité d’un package ».

Authentification avec un personal access token

Vous avez besoin d’un jeton d’accès pour publier, installer et supprimer des packages privés, internes et publics.

Vous pouvez utiliser un personal access token (classic) pour vous authentifier auprès de GitHub Packages ou de l’API GitHub. Quand vous créez un personal access token (classic), vous pouvez l’attribuer à différentes étendues selon vos besoins. Pour plus d’informations sur les étendues liées aux packages pour un personal access token (classic), consultez À propos des autorisations pour les packages GitHub.

Pour vous authentifier sur un registre GitHub Packages dans un workflow GitHub Actions, vous pouvez utiliser :

• GITHUB_TOKEN pour publier des packages associés au dépôt du workflow.
• Un personal access token (classic) avec au moins read:packages la possibilité d'installer des paquets associés à d'autres référentiels privés (GITHUB_TOKEN peut être utilisé si le référentiel a un accès en lecture au paquet. Consultez Configuration du contrôle d’accès et de la visibilité d’un package.

Vous devez utiliser un personal access token (classic) avec les étendues appropriées pour publier et installer des packages dans GitHub Packages. Pour plus d’informations, consultez « Introduction aux packages GitHub ».

Pour vous authentifier auprès de GitHub Packages à l’aide de l’interface de ligne de commande (CLI) dotnet, créez un fichier nuget.config dans le répertoire de votre projet en indiquant GitHub Packages comme source sous packageSources pour le client CLI dotnet.

Vous devez remplacer :

• USERNAME avec le nom de votre compte personnel sur GitHub.
• TOKEN avec votre personal access token (classic).
• NAMESPACE avec le nom du compte personnel ou de l’organisation dans laquelle vos packages sont limités.

<?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>

Publication d'un package

Vous pouvez publier un paquet sur GitHub Packages en vous authentifiant à l’aide d’un fichier nuget.config, en utilisant l’option de ligne de commande --api-key avec votre GitHubpersonal access token (classic), ou en utilisant une commande pouvant être exécutée directement depuis la ligne de commande à l’aide de l’interface de ligne de commande dotnet (CLI).

Remplacez OWNER par votre nom d’utilisateur ou votre nom d’entreprise, et YOUR_GITHUB_PAT par votre personal access token.

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

Le registre NuGet stocke les packages dans votre compte d’organisation ou personnel et vous autorise à associer les packages à un dépôt. Vous pouvez choisir d’hériter des autorisations d’un dépôt ou de définir des autorisations granulaires indépendamment d’un dépôt.

Lorsque vous publiez un package pour la première fois, la visibilité par défaut est privée. Pour modifier la visibilité ou définir les autorisations d’accès, consultez Configuration du contrôle d’accès et de la visibilité d’un package. Pour plus d’informations sur la liaison d’un package publié avec un référentiel, consultez Connexion d’un dépôt à un package.

Si vous spécifiez un RepositoryURL dans le fichier .csproj de votre project, le package publié est automatiquement connecté au référentiel spécifié. Pour plus d’informations, consultez Utilisation du registre NuGet. Pour plus d’informations sur la liaison d’un package déjà publié à un référentiel, consultez Connexion d’un dépôt à un package.

Publication d’un package à l’aide d’un GitHub personal access token en tant que clé API

Si vous n’avez pas encore de personal access token à utiliser avec votre compte sur GitHub, consultez Gestion de vos jetons d’accès personnels.

1. Créez un nouveau projet. Remplacez PROJECT_NAME par le nom que vous souhaitez donner à la project.

   dotnet new console --name PROJECT_NAME
   

2. Empaquetez le projet.

   dotnet pack --configuration Release
   

3. Publiez le package à l’aide de votre personal access token clé API. Remplacez PROJECT_NAME par le nom du projet, 1.0.0 par le numéro de version du package et YOUR_GITHUB_PAT par votre personal access token.

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

Après avoir publié un package, vous pouvez l'afficher sur GitHub. Pour plus d’informations, consultez « Affichage de packages ».

Publication d’un package à l’aide d’un fichier nuget.config

Lors de la publication, si vous liez votre package à un référentiel, le OWNER référentiel spécifié dans votre fichier .csproj doit correspondre à celui NAMESPACE que vous utilisez dans votre fichier d’authentification nuget.config . Spécifiez ou incrémentez le numéro de version dans votre fichier .csproj, puis utilisez la commande dotnet pack pour créer un fichier .nuspec pour cette version. Pour plus d’informations sur la création de votre package, consultez Créer et publier un package dans la documentation Microsoft.

1. Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez Authentification auprès de GitHub Packages.

2. Créez un nouveau projet. Remplacez PROJECT_NAME par le nom que vous souhaitez donner à la project.

   dotnet new console --name PROJECT_NAME
   

3. Ajoutez les informations spécifiques de votre projet au fichier de votre projet, qui se termine par .csproj. Veillez à remplacer :

   • 1.0.0 avec le numéro de version du paquet.
   • OWNER avec le nom du compte personnel ou de l’organisation qui possède le référentiel auquel vous souhaitez lier votre package.
   • REPOSITORY avec le nom du référentiel auquel vous souhaitez connecter votre package.

   <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. Empaquetez le projet.

   dotnet pack --configuration Release
   

5. Publiez le package avec la key que vous avez spécifiée dans le fichier nuget.config. Remplacez PROJECT_NAME par le nom du project, puis remplacez 1.0.0 par le numéro de version du package.

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

Après avoir publié un package, vous pouvez l'afficher sur GitHub. Pour plus d’informations, consultez « Affichage de packages ».

Publication de plusieurs packages sur le même dépôt

Pour connecter plusieurs packages au même dépôt, utilisez la même GitHub URL de dépôt dans les RepositoryURL champs de tous les fichiers projet .csproj . GitHub correspond au référentiel en fonction de ce champ.

L’exemple suivant publie les projets MY_APP et MY_OTHER_APP dans le même dépôt :

<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>

Installation d’un package

L’utilisation de packages provenant de GitHub dans votre projet est similaire à l’utilisation de packages de nuget.org. Ajoutez les dépendances de votre package à votre fichier .csproj, en spécifiant le nom et la version du package. Pour plus d’informations sur l’utilisation d’un fichier .csproj dans votre projet, consultez Travailler avec des packages NuGet dans la documentation Microsoft.

1. Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez Authentification auprès de GitHub Packages.

2. Pour utiliser un package, ajoutez ItemGroup et configurez le champ PackageReference dans le fichier .csproj project. Remplacez la valeur PACKAGE_NAME dans Include="PACKAGE_NAME" par votre dépendance de package et remplacez la valeur X.X.X dans Version="X.X.X" par la version du package que vous voulez utiliser :

   <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. Installez les packages avec la commande restore.

   dotnet restore
   

Dépannage

Si vous utilisez un GITHUB_TOKEN pour vous authentifier auprès d’un GitHub Packages registre au sein d’un GitHub Actions workflow, le jeton ne peut pas accéder aux packages privés basés sur un référentiel privé dans un autre référentiel que celui dans lequel le flux de travail s’exécute. Pour accéder aux packages associés à d’autres référentiels, générez plutôt un personal access token (classic) avec la portée read:packages, puis passez ce jeton comme secret.

Erreurs 403 intermittentes lors de la restauration de packages publics

Si vous utilisez GitHub Packages avec nuget.org et que vous rencontrez des erreurs intermittentes 403 Interdit lors de la restauration de packages publics standard (par exemple Microsoft.Extensions.*), cela peut se produire, car NuGet interroge toutes les sources de package configurées pour chaque package. Si GitHub Packages l’authentification échoue temporairement, elle peut bloquer l’intégralité de la restauration, même pour les packages qui n’existent pas sur GitHub Packages.

Pour éviter cela, utilisez le mappage de source de package NuGet pour router les packages vers des sources spécifiques.

Remplacez :

• NAMESPACE avec le nom du compte personnel ou de l’organisation propriétaire de votre GitHub Packages flux NuGet.
• PACKAGE-ID-PREFIX avec le préfixe d’ID de package NuGet que vous utilisez pour les packages hébergés sur GitHub Packages. Si vous utilisez plusieurs préfixes, ajoutez des entrées supplémentaires <package> pour chaque préfixe.

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

NuGet utilise le modèle de correspondance le plus spécifique, de sorte que les packages correspondants PACKAGE-ID-PREFIX.* ne sont extraits qu’à partir de GitHub Packages, tandis que tous les autres packages sont extraits de nuget.org. Cela permet également d’éviter les attaques de confusion des dépendances en garantissant que vos packages privés ne peuvent provenir que de votre GitHub Packages flux.

Pour approfondir

• Suppression et restauration d'un package