Trabalhando com o registro NuGet

Autenticar-se no GitHub Packages

O GitHub Packages dá suporte apenas à autenticação que usa um personal access token (classic). Para obter mais informações, confira "Como criar um personal access token".

Você precisa de um token de acesso para publicar, instalar e excluir pacotes privados, públicos e internos.

Você pode usar um personal access token (classic) para se autenticar no GitHub Packages ou na API do GitHub. Ao criar um personal access token (classic), você pode atribuir diferentes escopos de token, dependendo da sua necessidade. Para obter mais informações sobre escopos relacionados a pacotes para um personal access token (classic), 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 personal access token (classic) com pelo menos escopo read:packages para instalar pacotes associados a outros repositórios privados (que não podem ser acessados por GITHUB_TOKEN).

Como se autenticar em um fluxo de trabalho de GitHub Actions

Esse registro dá suporte a permissões granulares. Para registros que dão suporte a permissões granulares, se seu fluxo de trabalho GitHub Actions estiver usando um personal access token para autenticar em um registro, será altamente recomendável que você atualize seu fluxo de trabalho de modo que ele use o GITHUB_TOKEN. Para obter diretrizes sobre como atualizar seus fluxos de trabalho que se autenticam em um registro com um personal access token, confira "Como fazer upgrade de um fluxo de trabalho que acessa um registro usando um personal access token".

Observação: a capacidade dos fluxos de trabalho do GitHub Actions de excluir e restaurar pacotes usando a API REST está atualmente em versão beta pública e sujeita a alterações.

Você poderá usar um GITHUB_TOKEN em um fluxo de trabalho GitHub Actions para excluir ou restaurar pacotes usando a API REST, se o token tiver permissão admin para o pacote. Repositórios que publicam pacotes usando um fluxo de trabalho e repositórios conectados explicitamente a pacotes recebem permissão admin para pacotes no repositório automaticamente.

Para obter mais informações sobre o GITHUB_TOKEN, confira "Autenticação em um fluxo de trabalho". Para obter mais informações sobre as melhores práticas ao usar um registro em ações, confira "Proteção de segurança para GitHub Actions".

Use o seguinte comando para autenticar o GitHub Packages em um fluxo de trabalho do GitHub Actions usando o GITHUB_TOKEN em vez de codificar um personal access token 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"

Você também pode optar por dar permissões de acesso a pacotes de modo independente para GitHub Codespaces e GitHub Actions. Para obter mais informações, confira "Como garantir que os codespaces acessem seu pacote" e "Como garantir o acesso do fluxo de trabalho ao seu pacote".

Autenticar com um personal access token

O GitHub Packages dá suporte apenas à autenticação que usa um personal access token (classic). Para obter mais informações, confira "Como criar um personal access token".

Você precisa de um token de acesso para publicar, instalar e excluir pacotes privados, públicos e internos.

Você pode usar um personal access token (classic) para se autenticar no GitHub Packages ou na API do GitHub. Ao criar um personal access token (classic), você pode atribuir diferentes escopos de token, dependendo da sua necessidade. Para obter mais informações sobre escopos relacionados a pacotes para um personal access token (classic), 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 personal access token (classic) com pelo menos escopo read:packages para instalar pacotes associados a outros repositórios privados (que não podem ser acessados por GITHUB_TOKEN).

Você precisa usar um personal access token (classic) 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 com seu personal access token (classic).
OWNER com o nome do usuário ou conta da organização que possui o pacote que deseja instalar ou no qual deseja publicar um pacote.

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

Você pode publicar um pacote no GitHub Packages autenticando com um arquivo nuget.config ou usando a opção de linha de comando --api-key com seu GitHub personal access token (classic).

O registro do NuGet armazena pacotes em sua organização ou conta pessoal e permite que você associe pacotes a um repositório. Você pode escolher se deve herdar permissões de um repositório ou definir permissões granulares, independentemente de um repositório.

Ao publicar um pacote pela primeira vez a visibilidade-padrão será privada. Quando um pacote é vinculado a um repositório, a visibilidade do pacote depende da visibilidade do repositório. Para alterar a visibilidade ou definir permissões de acesso, confira "Como configurar o controle de acesso e a visibilidade de um pacote". Para obter mais informações sobre como vincular um pacote publicado a um repositório, confira "Como conectar um repositório a um pacote".

Se você especificar RepositoryURL em seu arquivo nuget.config, o pacote publicado será automaticamente conectado ao repositório especificado. Para obter mais informações, confira "Como publicar um pacote usando um arquivo nuget.config". Para obter informações sobre como vincular um pacote já publicado a um repositório, confira "Como conectar um repositório a um pacote".

Como publicar um pacote usando um GitHub personal access token como sua chave de API

Se você ainda não tem um PAT para usar em sua conta no GitHub.com, confira "Como criar um personal access token".

Criar um novo projeto.
```
dotnet new console --name OctocatApp
```
Empacotar o projeto.
```
dotnet pack --configuration Release
```

Publicar o pacote usando seu personal access token como a chave de 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.

Autenticar para GitHub Packages. Para obter mais informações, confira "Autenticação no GitHub Packages".
Criar um novo projeto.
```
dotnet new console --name OctocatApp
```

Adicione informações específicas do seu projeto ao arquivo do projeto, que termina com .csproj. Você deve substituir:

OWNER com o nome da conta de usuário ou da organização que possui o repositório ao qual você deseja conectar seu pacote.
REPOSITORY com o nome do repositório ao qual você deseja conectar seu pacote.
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>

Empacotar o projeto.
```
dotnet pack --configuration Release
```
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 conectar vários pacotes ao mesmo repositório, você pode incluir o mesmo URL de 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.

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

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>

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. Para acessar pacotes associados a outros repositórios, em vez disso, gere um personal access token (classic) com o escopo read:packages e passe esse token como um segredo.

Leitura adicional

"Como excluir e restaurar um pacote"