Надежная публикация в nuget.org

Надежная публикация — это лучший способ публикации пакетов NuGet. Вам больше не нужно управлять долгосрочными ключами API. Вместо этого вы используете короткие учетные данные, выданные системой CI/CD, например GitHub Actions.

Это делает процесс публикации более безопасным, уменьшая риск утечки учетных данных. Это также упрощает автоматизацию, так как вам не нужно обновлять или хранить секреты. Этот подход является частью более широкого отраслевого перехода на безопасную публикацию без ключей. Если вам интересно, ознакомьтесь с инициативой OpenSSF: https://repos.openssf.org/trusted-publishers-for-all-package-repositories

⚠️ Внимание: если вы не видите опцию надежной публикации в учетной записи на nuget.org, это может означать, что она еще недоступна для вас. Мы развертываем его постепенно.

Принцип работы

При запуске рабочего процесса GitHub Actions он запрашивает зашифрованный токен OIDC из github.com. Этот токен содержит сведения о вашем репозитории и рабочем процессе и криптографически подписан GitHub Actions, чтобы предотвратить несанкционированные изменения. Рабочий процесс перенаправляет этот токен на nuget.org, который надежно проверяет его подлинность через github.com, используя стандартные методы криптографии. Конечная точка обмена маркерами на nuget.org проверяет соответствие сведений о маркере доверенной политике публикации, которую вы настроили. Если все соответствует, nuget.org выдает кратковременный ключ API для рабочего процесса, который будет использоваться при публикации пакета.

Ниже приведен базовый поток

  1. Система CI/CD (например, GitHub Actions) выполняет рабочий процесс.
  2. Он выдает краткосрочный токен.
  3. Этот маркер отправляется в nuget.org.
  4. NuGet проверяет его и возвращает временный ключ API.
  5. Рабочий процесс использует этот ключ для отправки пакета.

Снимок экрана, отображающий страницу Trusted Publishing.

Временные ключи API NuGet действительны в течение 1 часа, поэтому рабочий процесс должен запросить ключ незадолго до публикации. Если вы запрашиваете его слишком рано, срок действия может истечь до отправки.

Каждый кратковременный токен можно использовать только один раз для получения одного временного ключа API — одного токена, одного ключа API.

Эта настройка обеспечивает безопасный и автоматизированный способ публикации пакетов без рисков, которые приходят с длительными секретами.

Настройка действий GitHub

Чтобы приступить к работе, выполните приведенные действия.

  1. Войдите в nuget.org.
  2. Щелкните имя пользователя и выберите "Надежная публикация".
  3. Добавьте новую политику надежной публикации. Для репозитория https://github.com/contoso/contoso-sdk GitHub с файлом .github/workflows/build.yml рабочего процесса укажите данные о доверенной политике (без учета регистра):
    • Владелец репозитория:contoso
    • Хранилище:contoso-sdk
    • Файл рабочего процесса:build.yml

      Это соответствует рабочему процессу по адресу .github/workflows/build.yml. Введите только имя файла (build.yml)— не включайте .github/workflows/ путь.

    • Среда (необязательно):release

      Введите среду, если рабочий процесс использует, например environment: release , и вы хотите ограничить эту политику этой средой. Оставьте это пустым, если вы не используете среды GitHub Actions.

  4. В репозитории GitHub обновите рабочий процесс, чтобы запросить кратковременный ключ API и отправить пакет.
    Ниже приведен базовый пример.
jobs:
  build-and-publish:
    permissions:
      id-token: write  # enable GitHub OIDC token issuance for this job
    
    steps:
      # Build your artifacts/my-sdk.nupkg package here
    
      # Get a short-lived NuGet API key
      - name: NuGet login (OIDC → temp API key)
        uses: NuGet/login@v1
        id: login
        with:
          user: contoso-bot # Recommended: use a secret like ${{ secrets.NUGET_USER }} for your nuget.org username (profile name), NOT your email address
    
      # Push the package
      - name: NuGet push
        run: dotnet nuget push artifacts/my-sdk.nupkg --api-key ${{steps.login.outputs.NUGET_API_KEY}} --source https://api.nuget.org/v3/index.json

Владение политикой

При создании политики доверенной публикации необходимо выбрать владельца. Владелец может быть следующим:

  • Вы (отдельный пользователь)
  • Организация, к которой вы принадлежите

Политика будет применяться ко всем пакетам, принадлежащим выбранному владельцу. Это означает, что он управляет тем, кто может публиковать или изменять эти пакеты с помощью доверенной публикации.

Если вы выбираете организацию, убедитесь, что вы являетесь активным участником. Если вы покинете организацию, политика может стать неактивной до тех пор, пока вас не добавят обратно.

Выбор правильного владельца помогает обеспечить безопасность и соответствие настройки публикации структуре вашей команды.

Политики, ожидающие полной активации

Иногда при создании политики надежной публикации она становится временно активной на 7 дней. Обычно это происходит с частным репозиторием GitHub. Вы увидите это состояние в пользовательском интерфейсе. В течение этого времени она ведет себя как обычная политика. Но если публикация не выполняется в течение этих 7 дней, политика автоматически становится неактивной. Вы можете перезапустить 7-дневное окно в любое время, даже после истечения срока действия.

Почему этот временный период необходим? Поскольку NuGet требует идентификаторов репозитория GitHub и владельца, чтобы привязать политику к исходному репозиторию и его владельцу. Это помогает предотвратить атаки восстановления. Без этих идентификаторов кто-то может удалить репозиторий, повторно создать его с тем же именем и попытаться опубликовать, как если бы ничего не изменилось.

После успешной публикации, которая предоставляет идентификаторы (в рамках кратковременного маркера GitHub), политика становится перманентно активной.

Предупреждения об ответственности за политику

Политики доверенной публикации привязаны к конкретному владельцу — отдельному пользователю или организации. Если что-то изменится с этим владельцем, политика может стать неактивной. В этом случае в пользовательском интерфейсе появится предупреждение.

Распространенные случаи

  • Пользователь удален из организации
    Если политика принадлежит организации и пользователь, создавший её, удален из этой организации, политика перестаёт действовать.
    Если пользователь добавляется обратно в организацию, политика будет активна автоматически.

  • Организация больше не активна
    Если организация, которая владеет политикой, заблокирована или удалена, политика становится неактивной.

Эти предупреждения помогают убедиться, что при публикации пакетов используются только активные, безопасные политики.

  • Last updated on