Skip to main content

Trabalhando com o registro NuGet

Você pode configurar a CLI (interface de linha de comando) dotnet para publicar pacotes NuGet no GitHub Packages e usar pacotes armazenados no GitHub Packages como dependências em um projeto .NET.

O GitHub Packages está disponível com GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 ou superior e o GitHub AE.
O GitHub Packages não está disponível para repositórios privados de contas que utilizam planos antigos por-repositório. Além disso, as contas que usam os planos de legado por repositório não podem acessar o Container registry já que essas contas são cobradas por repositório. Para obter mais informações, confira "produtos de GitHub".

Autenticar-se no GitHub Packages

Você precisa de um token de acesso para publicar, instalar e excluir pacotes.

Você pode usar um PAT (token de acesso pessoal) para se autenticar no GitHub Packages ou na API do GitHub. Ao criar um token de acesso pessoal, você pode atribuir diferentes escopos de token, dependendo da sua necessidade. Para obter mais informações sobre escopos relacionados a pacotes para um PAT, confira "Sobre as permissões para pacotes do GitHub".

Para efetuar a autenticação em um registro do GitHub Packages dentro de um fluxo de trabalho de GitHub Actions, você pode utilizar:

  • GITHUB_TOKEN para publicar pacotes associados ao repositório do fluxo de trabalho.
  • um PAT para instalar pacotes associados a outros repositórios privados (que não podem ser acessados pelo GITHUB_TOKEN).

Autenticação com o GITHUB_TOKEN no GitHub Actions

Use o comando a seguir para se autenticar no GitHub Packages em um fluxo de trabalho do GitHub Actions usando o GITHUB_TOKEN, em vez de embutir um token em código em um arquivo nuget.config no repositório:

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

Para obter mais informações sobre o GITHUB_TOKEN usado em fluxos de trabalho do GitHub Actions, confira "Autenticação em um fluxo de trabalho".

Efetuando a autenticação com um token de acesso pessoal

Você deve usar um token de acesso pessoal com os escopos apropriados para publicar e instalar pacotes no GitHub Packages. Para obter mais informações, confira "Sobre o GitHub Packages".

Para se autenticar no GitHub Packages com a CLI (interface de linha de comando) do dotnet, crie um arquivo nuget.config no diretório do projeto especificando o GitHub Packages como uma fonte em packageSources para o cliente da CLI do dotnet.

Você deve substituir:

  • USERNAME com o nome de sua conta de usuário em GitHub.
  • TOKEN pelo seu token de acesso pessoal.
  • OWNER pelo nome da conta de usuário ou de organização que é o proprietário do repositório que contém o projeto.
<?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>

Publicando um pacote

Publique um pacote no GitHub Packages autenticando-se com um arquivo nuget.config ou usando a opção --api-key de linha de comando com seu PAT (token de acesso pessoal) do GitHub.

Publicar um pacote usando um o PAT do GitHub como sua chave da API

Se você ainda não tem um PAT para uso na sua conta no GitHub.com, confira "Como criar um token de acesso pessoal".

  1. Criar um novo projeto.

    dotnet new console --name OctocatApp
  2. Empacotar o projeto.

    dotnet pack --configuration Release
  3. Publique o pacote usando o seu PAT como a chave da API.

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

Após publicar um pacote, você poderá visualizá-lo no GitHub. Para obter mais informações, confira "Como ver pacotes".

Como publicar um pacote usando um arquivo nuget.config

Para a publicação, você precisa usar o mesmo valor para OWNER no arquivo csproj usado no arquivo de autenticação nuget.config. Especifique ou incremente o número de versão no arquivo .csproj e use o comando dotnet pack para criar um arquivo .nuspec para essa versão. Para obter mais informações sobre como criar seu pacote, confira "Criar e publicar um pacote" na documentação da Microsoft.

  1. Autenticar para GitHub Packages. Para obter mais informações, confira "Autenticação no GitHub Packages".

  2. Criar um novo projeto.

    dotnet new console --name OctocatApp
  3. Adicione informações específicas do seu projeto ao arquivo do projeto, que termina com .csproj. Você deve substituir:

    • OWNER pelo nome da conta de usuário ou de organização que é o proprietário do repositório que contém o projeto.
    • REPOSITORY pelo nome do repositório que contém o pacote que você deseja publicar.
    • 1.0.0 pelo número de versão do pacote.
    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.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>
    
    </Project>
    
  4. Empacotar o projeto.

    dotnet pack --configuration Release
  5. Publique o pacote usando a key que você especificou no arquivo nuget.config.

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

Após publicar um pacote, você poderá visualizá-lo no GitHub. Para obter mais informações, confira "Como ver pacotes".

Publicar vários pacotes no mesmo repositório

Para publicar vários pacotes no mesmo repositório, você pode incluir a mesma URL do repositório do GitHub nos campos RepositoryURL em todos os arquivos de projeto .csproj. O GitHub corresponde ao repositório baseado nesse campo.

Por exemplo, os projetos OctodogApp e OctocatApp serão publicados no mesmo repositório:

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>OctodogApp</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octodog</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds an Octodog!</PackageDescription>
    <RepositoryUrl>https://github.com/octo-org/octo-cats-and-dogs</RepositoryUrl>
  </PropertyGroup>

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.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/octo-org/octo-cats-and-dogs</RepositoryUrl>
  </PropertyGroup>

</Project>

Instalando um pacote

O uso de pacotes do GitHub no projeto é semelhante ao uso de pacotes de nuget.org. Adicione as dependências do pacote ao arquivo .csproj especificando o nome e a versão do pacote. Para obter mais informações sobre como usar um arquivo .csproj no seu projeto, confira "Como trabalhar com pacotes NuGet" na documentação da Microsoft.

  1. Autenticar para GitHub Packages. Para obter mais informações, confira "Autenticação no GitHub Packages".

  2. Para usar um pacote, adicione ItemGroup e configure o campo PackageReference no arquivo de projeto .csproj. Substitua o valor OctokittenApp em Include="OctokittenApp" por sua dependência de pacote e o valor 12.0.2 em Version="12.0.2" pela versão que você deseja usar:

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.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>
    
  3. Instale os pacotes com o comando restore.

    dotnet restore

Solução de problemas

Talvez o pacote NuGet não consiga efetuar push se a RepositoryUrl no .csproj não está definida como o repositório esperado.

Se você estiver usando um arquivo nuspec, verifique se ele tem um elemento repository com os atributos type e url obrigatórios.

Se você estiver usando um GITHUB_TOKEN para autenticação em um registro GitHub Packages em um fluxo de trabalho GitHub Actions, o token não poderá acessar pacotes baseados em repositório privado em um repositório diferente de onde o fluxo de trabalho está sendo executado. Alternativamente, para acessar pacotes associados a outros repositórios, gere um PAT com o escopo read:packages e passe esse token como um segredo.

Leitura adicional