Токены stage-only в npm: какие подтверждения фиксировать при разделении автоматизации публикации и финального утверждения
Разделение прав CI на сборку пакета и прав на его публикацию для пользователей делает финальную ответственность за релиз более прозрачной. Однако простое добавление кнопки утверждения не устраняет риски для цепочки поставок. Прежде всего необходимо определить, что именно проверяет утверждающий.
18 сентября GitHub объявил о появлении права на запись stage-only для гранулярных токенов доступа (granular access tokens) npm. Схема работает следующим образом: автоматизация отправляет версию на стадию ожидания проверки, а мейнтейнер подтверждает публикацию с помощью 2FA. Ниже приведено описание официальных изменений в сочетании с практическими рекомендациями редакции по их внедрению в процессы.
Блокировка прямой публикации не означает полное лишение прав на запись
Согласно официальному руководству, с помощью такого токена можно выполнять команду npm stage publish, но прямая публикация через npm publish будет отклонена. Это ограничение действует даже при наличии настройки обхода 2FA для автоматизации. Поведение существующих токенов автоматически не меняется, функция внедряется выборочно.
Следует учитывать, что другие права на запись в пакет — такие как перенос dist-tag или объявление версий устаревшими (deprecation) — сохраняются. Название stage-only не следует воспринимать как токен только для чтения или полностью безопасный. По-прежнему необходимо контролировать область разрешенных пакетов, места хранения секретов, субъекты использования и процедуры отзыва.
Определите состав пакета релиза, который сверяет утверждающий
Следующие рекомендации не являются обязательными требованиями npm, а представляют собой предложения для небольших команд. Прикрепляйте к каждому запросу на утверждение коммит исходного кода, целевой пакет и версию, результаты тестов, список файлов, входящих в пакет, и краткое описание изменений. Если утверждающему приходится собирать подтверждения из разных логов CI, проверка быстро превратится в формальный клик.
В частности, проверка исходного кода и проверка файлов дистрибутива — это разные вещи. Файлы, отсутствовавшие в репозитории, могут попасть в сборку, а необходимые файлы могут оказаться пропущенными. Команда может принять правило формировать материалы для проверки на основе фактически отправляемых артефактов и рассматривать любые изменения артефактов после проверки как повод для повторного ревью.
После успешного прохождения CI наступает состояние ожидания
Если прежняя автоматизация трактовала успешное выполнение команды как завершение релиза, необходимо изменить отображение статусов. Следует разделять этапы: отправка завершена, ожидает утверждения и опубликовано, фиксируя основания для каждого из них. В уведомлениях операторам гораздо полезнее видеть текущий этап и ответственного, чем простое слово «успех».
В качестве гипотетического примера: если ночной CI отправил новую версию, а ответственный проверит ее только на следующий день, в момент отправки нельзя рассылать анонс релиза пользователям. Настройте цепочку так, чтобы документация или анонсы публиковались только после подтверждения публикации, установленного командой. Также необходимо заранее договориться, кто проверяет накопившуюся очередь и когда закрываются устаревшие отправки.
Проверьте миграцию на одном небольшом пакете
На данный момент предварительные условия в официальном руководстве включают существующий пакет npm, права на публикацию пакета, 2FA учетной записи, npm CLI версии 11.15.0 или выше и Node.js 22.14.0 или выше. Перед реальной миграцией следует повторно свериться с актуальной документацией и проверить версии используемых раннеров (runners).
Для начала рекомендуется ограничить область действия токена на одном низкорисковом пакете и отработать весь процесс: отправку на staging, проверку мейнтейнером и подтверждение результатов публикации. Если при сбое сразу переключаться на старый токен с широкими правами, созданная граница безопасности потеряет смысл. Задержка утверждения также должна обрабатываться как штатная ситуация.
Вопросы для сравнения с trusted publishing
npm также предлагает механизм trusted publishing с использованием OIDC. В первую очередь следует оценить, подходит ли он под поддерживаемое CI-окружение и принятые в команде процедуры утверждения; не стоит считать токен stage-only универсальным решением для всех. Для систем автоматизации, где использование токенов неизбежно, это новшество можно рассматривать как удобный вариант поэтапного перехода.
В официальном анонсе целевым сроком прекращения прямой публикации по токенам с обходом 2FA (bypass-2FA) назван январь 2027 года. Вместо догадок обо всех деталях будущей реализации практичнее уже сейчас составить список задействованных воркфлоу и назначить ответственных за миграцию. О возможных изменениях в графике следует узнавать из последующих официальных объявлений.
Что учесть при принятии решения о внедрении
Эта статья не претендует на выражение широкого консенсуса сообщества или статистику снижения числа инцидентов. В ней предложены проверяемые операционные процедуры на основе официального поведения новой функции. Отправная точка для решения о внедрении — четкое понимание того, какие задачи поручаются автоматизации, а что именно должен проверять человек.
Шаги, которые можно предпринять уже сегодня: найти места использования текущих релизных токенов, зафиксировать критерии завершения публикации и определить набор подтверждений, требуемых для разового утверждения. Этап staging принесет реальную пользу только в том случае, если ограничение прав сопровождается должным качеством проверок.