Работа с реестром NuGet

Интерфейс командной строки можно настроить dotnet для публикации пакетов GitHub Packages NuGet и использования пакетов, хранящихся GitHub Packages в качестве зависимостей в проекте .NET.

Кто может использовать эту функцию?

Enterprise Managed Users может публиковаться в пространстве имен организации. Эти пользователи не могут публиковать пакеты в пространстве имен своей учетной записи, так как личные ресурсы хранилища отсутствуют. Дополнительные сведения о Enterprise Managed Usersсм. в разделе Сведения о Enterprise Managed Users.

В этой статье

URL-адрес реестра NuGet

Если вы обращаетесь по адресу GitHubGitHub.com, вы опубликуете пакеты https://nuget.pkg.github.comв . Примеры в этой статье используют этот URL-адрес.

Если вы обращаетесь GitHub к другому домену, например octocorp.ghe.com, замените "https://nuget.pkg.github.com" https://nuget.SUBDOMAIN.ghe.comна , где SUBDOMAIN находится уникальный поддомен вашего предприятия.

Аутентификация в GitHub Packages

Примечание.

GitHub Packages поддерживает проверку подлинности только с помощью personal access token (classic). Дополнительные сведения см. в разделе Управление личными маркерами доступа.

Для публикации, установки и удаления частных, внутренних и общедоступных пакетов требуется маркер доступа.

Можно использовать personal access token (classic) для проверки подлинности в API GitHub Packages или API GitHub . При создании personal access token (classic)можно назначить маркер различным областям в зависимости от ваших потребностей. Дополнительные сведения о областях, связанных с пакетами, для personal access token (classic), см. в разделе Сведения о разрешениях для пакетов GitHub.

Для проверки подлинности в реестре GitHub Packages в рабочем процессе GitHub Actions можно использовать следующее:

  • GITHUB_TOKEN для публикации пакетов, связанных с репозиторием рабочих процессов.
  • personal access token (classic) с по крайней мере read:packages областью действия для установки пакетов, связанных с другими частными репозиториями (GITHUB_TOKEN можно использовать, если репозиторий предоставлен доступ на чтение к пакету. См . раздел AUTOTITLE.

Проверка подлинности в GitHub Actions рабочем процессе

Этот реестр поддерживает детализированные разрешения. Для реестров, поддерживающих детализированные разрешения, если рабочий процесс GitHub Actions использует personal access token для проверки подлинности в реестре, настоятельно рекомендуется обновить рабочий процесс для использования GITHUB_TOKEN. Инструкции по обновлению рабочих процессов, прошедших проверку подлинности в реестре с помощью personal access token, см. в разделе Публикация и установка пакета с помощью GitHub Actions.

Примечание.

Возможность удаления и восстановления пакетов с помощью REST API GitHub Actions в настоящее время находится в Публичный предварительный просмотр и подлежит изменению.

Вы можете использовать GITHUB_TOKEN рабочий процесс GitHub Actions для удаления или восстановления пакета с помощью REST API, если маркер имеет admin разрешение на пакет. Репозитории, публикующие пакеты с помощью рабочего процесса и репозиториев, которые явно подключены к пакетам, автоматически предоставляются admin разрешения на пакеты в репозитории.

Дополнительные сведения см. в GITHUB_TOKENразделе Использование GITHUB_TOKEN для проверки подлинности в рабочих процессах. Дополнительные сведения о рекомендациях при использовании реестра в действиях см. в разделе Справочник по безопасному использованию.

Используйте следующую команду, чтобы пройти проверку подлинности GitHub Packages в GitHub Actions рабочем процессе, используя GITHUB_TOKEN вместо жесткого personal access token кода файл в nuget.config файле в репозитории:

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"

Замените NAMESPACE именем личной учетной записи или организации, в которой находятся пакеты, в которых находятся ваши пакеты.

Замените USERNAME имя пользователя, которое будет использоваться при подключении к источнику, прошедшему проверку подлинности.

Вы также можете предоставить доступ к пакетам независимо для GitHub Codespaces и GitHub Actions. Дополнительные сведения см. в разделе [AUTOTITLE и Настройка управления доступом и видимости пакета](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package).

Аутентификация с помощью personal access token

Примечание.

GitHub Packages поддерживает проверку подлинности только с помощью personal access token (classic). Дополнительные сведения см. в разделе Управление личными маркерами доступа.

Для публикации, установки и удаления частных, внутренних и общедоступных пакетов требуется маркер доступа.

Можно использовать personal access token (classic) для проверки подлинности в API GitHub Packages или API GitHub . При создании personal access token (classic)можно назначить маркер различным областям в зависимости от ваших потребностей. Дополнительные сведения о областях, связанных с пакетами, для personal access token (classic), см. в разделе Сведения о разрешениях для пакетов GitHub.

Для проверки подлинности в реестре GitHub Packages в рабочем процессе GitHub Actions можно использовать следующее:

  • GITHUB_TOKEN для публикации пакетов, связанных с репозиторием рабочих процессов.
  • personal access token (classic) с по крайней мере read:packages областью действия для установки пакетов, связанных с другими частными репозиториями (GITHUB_TOKEN можно использовать, если репозиторий предоставлен доступ на чтение к пакету. См . раздел AUTOTITLE.

Необходимо использовать personal access token (classic) с соответствующими областями для публикации и установки пакетов в GitHub Packages. Дополнительные сведения см. в разделе Введение в GitHub Packages.

Чтобы выполнить проверку подлинности GitHub Packages с помощью dotnet интерфейса командной строки (CLI), создайте _ файлnuget.config_ в каталоге проекта, GitHub Packages указывающий в качестве источника packageSources для dotnet клиента CLI.

Необходимо заменить:

  • USERNAME с именем вашей личной учетной записи GitHub.
  • TOKEN с вашим personal access token (classic).
  • NAMESPACE с именем личной учетной записи или организации , в которой находятся пакеты.
<?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>

Публикация пакета

Примечание.

Архив nupkg для версии пакета NuGet должен быть меньше 2,147 ГБ.

Вы можете опубликовать пакет GitHub Packages для проверки подлинности с _ помощью файлаnuget.config_ , используя --api-key параметр командной строки с вашей GitHubpersonal access token (classic) командой или с помощью команды, которая может выполняться непосредственно из командной строки с помощью dotnet интерфейса командной строки (CLI).

Замените OWNER имя пользователя или название компании и YOUR_GITHUB_PAT вашей.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"

Реестр NuGet хранит пакеты в организации или личная учетная запись и позволяет связывать пакеты с репозиторием. Можно указать, нужно ли наследовать разрешения из репозитория или задавать детализированные разрешения независимо от репозитория.

При первой публикации пакета для параметра видимости по умолчанию выбирается закрытый доступ. Чтобы изменить видимость или задать разрешения доступа, см. раздел Настройка управления доступом и видимости пакета. Дополнительные сведения о связывании опубликованного пакета с репозиторием см. в разделе Подключение репозитория к пакету.

Если вы укажете RepositoryURL в файле project .csproj, опубликованный пакет автоматически будет подключён к указанному репозиторию. Для получения дополнительной информации см. Работа с реестром NuGet. Для информации о связи уже опубликованного пакета с репозиторием см. Подключение репозитория к пакету.

Публикация пакета с помощью GitHub personal access token в качестве ключа API

Если у вас еще нет учетной personal access token записи GitHub, см. раздел Управление личными маркерами доступа.

  1. Создайте новый project. Замените PROJECT_NAME на имя, которое вы хотите дать project.

    dotnet new console --name PROJECT_NAME

  2. Упаковывайте project.

    dotnet pack --configuration Release

  3. Опубликуйте пакет с помощью personal access token ключа API. Замените PROJECT_NAME именем проекта, 1.0.0 номером версии пакета и YOUR_GITHUB_PAT вашим personal access token.

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

После публикации пакет можно просмотреть здесь: GitHub. Дополнительные сведения см. в разделе Просмотр пакетов.

Публикация пакета с помощью файла nuget.config

При публикации, если вы связываете пакет с репозиторием, репозиторий, указанный в CSPROJ-файле, OWNER должен соответствовать NAMESPACE используемому в файле проверки подлинности nuget.config. Укажите или увеличьте номер версии в CSPROJ-файле, а затем используйте команду dotnet pack, чтобы создать NUSPEC-файл для этой версии. Дополнительные сведения о создании пакета см. в статье "Создание и публикация пакета" в документации Майкрософт.

Примечание.

При публикации пакета, связанного с репозиторием, пакет автоматически наследует разрешения доступа связанного репозитория, а рабочие процессы GitHub Actions в связанном репозитории автоматически получают доступ к пакету, если ваша организация не отключила автоматическое наследование разрешений доступа. Дополнительные сведения см. в разделе Настройка управления доступом и видимости пакета.

  1. Пройдите проверку подлинности в GitHub Packages. Дополнительные сведения см. в разделе "Проверка подлинности в GitHub Packages.

  2. Создайте новый project. Замените PROJECT_NAME на имя, которое вы хотите дать project.

    dotnet new console --name PROJECT_NAME

  3. Добавьте конкретную информацию вашего project в файл вашего project, который заканчивается на .csproj. Замените:

    • 1.0.0 номер версии пакета.
    • OWNER с именем личной учетной записи или организации, владеющей репозиторием, с которым вы хотите связать пакет.
    • REPOSITORY с именем репозитория, к которому требуется подключить пакет.
    <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. Упаковывайте project.

    dotnet pack --configuration Release

  5. Опубликуйте пакет, используя key, указанный в файле nuget.config. Замените PROJECT_NAME на название project и замените 1.0.0 на номер версии упаковки.

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

После публикации пакет можно просмотреть здесь: GitHub. Дополнительные сведения см. в разделе Просмотр пакетов.

Публикация нескольких пакетов в одном репозитории

Чтобы подключить несколько пакетов к одному репозиторию, используйте один и тот же GitHub URL-адрес репозитория в полях во RepositoryURL всех файлах проекта CSPROJ . GitHub соответствует репозиторию на основе этого поля.

В следующем примере проекты публикуются MY_APP и MY_OTHER_APP в том же репозитории:

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

Установка пакета

Использование пакетов из GitHub проекта аналогично использованию пакетов из nuget.org. Добавьте зависимости пакета в CSPROJ-файл , указав имя пакета и версию. Для получения дополнительной информации об использовании файла .csproj в вашем project см. Работа с пакетами NuGet в документации Microsoft.

  1. Пройдите проверку подлинности в GitHub Packages. Дополнительные сведения см. в разделе "Проверка подлинности в GitHub Packages.

  2. Чтобы использовать пакет, добавьте ItemGroup и настройте поле PackageReference в файле .csproj project. Замените PACKAGE_NAME значение Include="PACKAGE_NAME" в зависимости пакета и замените X.X.X его Version="X.X.X" версией пакета, которую вы хотите использовать:

    <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. Установите пакеты с помощью команды restore.

    dotnet restore

Устранение неполадок

Если вы используете GITHUB_TOKEN проверку подлинности в GitHub Packages реестре GitHub Actions в рабочем процессе, маркер не может получить доступ к пакетам на основе частного репозитория в другом репозитории, отличном от того, где выполняется рабочий процесс. Чтобы получить доступ к пакетам, связанным с другими репозиториями, вместо этого создайте personal access token (classic)read:packages область с областью и передайте этот маркер в виде секрета.

Прерывистые ошибки 403 при восстановлении публичных пакетов

Если вы используете GitHub Packages вместе с nuget.org и испытываете периодические ошибки 403 Запрещено при восстановлении стандартных общедоступных пакетов (например), это может произойти, так как Microsoft.Extensions.*NuGet запрашивает все настроенные источники пакетов для каждого пакета. Если GitHub Packages проверка подлинности завершается временной ошибкой, она может блокировать весь процесс восстановления даже для пакетов, в которых нет GitHub Packages.

Чтобы избежать этого, используйте NuGet Package Source Mapping для маршрутизации пакетов к конкретным источникам.

Замените:

  • NAMESPACE с именем личной учетной записи или организации, которая владеет веб-каналом GitHub Packages NuGet.
  • PACKAGE-ID-PREFIX с префиксом идентификатора пакета NuGet, который используется для пакетов, размещенных в GitHub Packages. При использовании нескольких префиксов добавьте дополнительные <package> записи для каждого префикса.
<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 использует наиболее конкретный шаблон сопоставления, поэтому сопоставления PACKAGE-ID-PREFIX.* пакетов извлекаются только из GitHub Packagesних, а все остальные пакеты извлекаются из nuget.org. Это также помогает предотвратить атаки на путаницу зависимостей, гарантируя, что частные пакеты могут поступать только из GitHub Packages вашего веб-канала.

Дополнительные материалы