Enterprise Server 3.20 está disponível no momento como versão candidata a lançamento.

Trabalhando com o registro NuGet

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

Neste artigo

Observação

Talvez esse tipo de pacote não esteja disponível para sua instância, pois os administradores do site podem habilitar ou desabilitar cada tipo de pacote compatível. Para saber mais, confira Configuração do suporte ao ecossistema de pacotes para sua empresa.

Autenticar-se no GitHub Packages

Observação

O GitHub Packages dá suporte apenas à autenticação que usa um personal access token (classic). Para saber mais, confira Gerenciar seus tokens de acesso pessoal.

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 personal access token (classic), confira Sobre permissões para o GitHub Packages.

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 (GITHUB_TOKEN pode ser usado se o repositório receber acesso de leitura ao pacote. Confira, Configurando o controle de acesso e visibilidade de um pacote).

Como se autenticar em um fluxo de trabalho de 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.HOSTNAME/NAMESPACE/index.json"

Substitua NAMESPACE pelo nome da conta pessoal ou organização , que é proprietário do repositório no qual seus pacotes estão hospedados.

Substitua USERNAME pelo nome de usuário a ser usado ao se conectar a uma fonte autenticada.

Para obter mais informações sobre o GITHUB_TOKEN usado em fluxos de trabalho do GitHub Actions, confira Usar GITHUB_TOKEN para autenticação em fluxos de trabalho.

Autenticar com um personal access token

Observação

O GitHub Packages dá suporte apenas à autenticação que usa um personal access token (classic). Para saber mais, confira Gerenciar seus tokens de acesso pessoal.

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 personal access token (classic), confira Sobre permissões para o GitHub Packages.

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 (GITHUB_TOKEN pode ser usado se o repositório receber acesso de leitura ao pacote. Confira, Configurando o controle de acesso e visibilidade de um pacote).

Você precisa usar um personal access token (classic) com os escopos apropriados para publicar e instalar pacotes no GitHub Packages. Para saber mais, confira Introdução ao GitHub Packages.

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

Você deve substituir: * USERNAME com o nome de sua conta de usuário em GitHub. * TOKEN com seu personal access token (classic).

  •           `NAMESPACE` pelo nome da conta pessoal ou organização , que é proprietário do repositório no qual seus pacotes estão hospedados.

  •           `HOSTNAME` com o nome do host para sua instância do GitHub Enterprise Server.

Se a sua instância tiver o isolamento de subdomínio habilitado:

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

Se a sua instância tiver o isolamento de subdomínio desabilitado:

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

Publicando um pacote

Você pode publicar um pacote no GitHub Packages autenticando-se com um arquivo nuget.config, usando a opção de linha de comando do --api-key com seu GitHub personal access token (classic) ou usando um comando que possa ser executado diretamente da linha de comando usando a interface de linha de comando (CLI) do dotnet.

Substitua OWNER pelo seu nome de usuário ou nome da empresa e YOUR_GITHUB_PAT pelo seu 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"

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

Se você ainda não tiver um personal access token para usar para sua conta em GitHub, consulte Gerenciar seus tokens de acesso pessoal.

  1. Crie um novo project. Substitua PROJECT_NAME pelo nome que você gostaria de dar ao project.

    dotnet new console --name PROJECT_NAME

  2. Empacotar o projeto.

    dotnet pack --configuration Release

  3. Publique o pacote usando seu personal access token como chave de API. Substitua PROJECT_NAME pelo nome do projeto, 1.0.0 pelo número de versão do pacote e YOUR_GITHUB_PAT pelo personal access token.

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

Após publicar um pacote, você poderá visualizá-lo no GitHub. Para saber mais, confira Visualizar pacotes.

Como publicar um pacote usando um arquivo nuget.config

Ao publicar, o OWNER do repositório especificado em seu arquivo .csproj deverá corresponder ao NAMESPACE que você usa em seu 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 saber mais, confira Autenticação no GitHub Packages.

  2. Crie um novo project. Substitua PROJECT_NAME pelo nome que você gostaria de dar ao project.

    dotnet new console --name PROJECT_NAME

  3. Adicione as informações específicas do seu projeto ao arquivo do seu projeto, que termina em .csproj. Certifique-se de substituir:

    •      `1.0.0` pelo número de versão do pacote.

    •           `OWNER` pelo nome da conta pessoal ou organização que é proprietário do repositório ao qual você deseja publicar seu pacote.

    •      `REPOSITORY` com o nome do repositório ao qual você deseja conectar seu pacote.

    •           `HOSTNAME` com o nome do host para sua instância do 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. Empacote o projeto.

    dotnet pack --configuration Release

  5. Publique o pacote usando a key que você especificou no arquivo nuget.config. Substitua PROJECT_NAME pelo nome do project e substitua 1.0.0 pelo número de versão do pacote.

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

Após publicar um pacote, você poderá visualizá-lo no GitHub. Para saber mais, confira Visualizar pacotes.

Publicar vários pacotes no mesmo repositório

Para conectar vários pacotes ao mesmo repositório, use a mesma URL do repositório GitHub nos campos RepositoryURL em todos os arquivos .csproj. O GitHub corresponde ao repositório baseado nesse campo.

O seguinte exemplo publica os projetos MY_APP e MY_OTHER_APP no mesmo repositório:

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

Instalando um pacote

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

  1. Autenticar para GitHub Packages. Para saber mais, confira Autenticação no GitHub Packages.

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

    <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 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 estiver 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 autenticar em um registro GitHub Packages dentro de um fluxo de trabalho GitHub Actions, o token não poderá acessar pacotes baseados em um repositório privado diferente daquele 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.

Erros intermitentes 403 ao restaurar pacotes públicos

Se você estiver usando GitHub Packages juntamente com nuget.org e enfrentando erros intermitentes 403 Proibido ao restaurar pacotes públicos padrão (como Microsoft.Extensions.*), isso pode ocorrer porque o NuGet consulta todas as fontes de pacote configuradas para cada pacote. Se a autenticação de GitHub Packages falhar temporariamente, ela poderá bloquear toda a restauração, mesmo para pacotes que não existem em GitHub Packages.

Para evitar isso, use o Mapeamento de Origem do Pacote NuGet para rotear pacotes para fontes específicas.

Substituir:

  •           `NAMESPACE` com o nome da conta pessoal ou organização que tem o feed NuGet do GitHub Packages.

  •           `PACKAGE-ID-PREFIX` com o prefixo de ID do pacote NuGet que você usa para pacotes hospedados em GitHub Packages. Se você usar vários prefixos, adicione mais entradas `<package>` para cada prefixo.

  •           `HOSTNAME` com o nome do host para sua instância do GitHub Enterprise Server.

Se a sua instância tiver o isolamento de subdomínio habilitado:

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

Se a sua instância tiver o isolamento de subdomínio desabilitado:

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

O NuGet usa o padrão de correspondência mais específico, de modo que os pacotes que correspondem a PACKAGE-ID-PREFIX.* são buscados somente de GitHub Packages, enquanto todos os outros pacotes são buscados de nuget.org. Isso também ajuda a evitar ataques de confusão de dependência, garantindo que seus pacotes privados só possam vir do feed do seu GitHub Packages.

Leitura adicional

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