Публикувайте npm пакет без дългоживеещ токен — OIDC оставя доказуем произход

За да публикувате npm пакет от GitHub Actions без постоянен write token, настройте trusted publisher за конкретния пакет и workflow. Дайте на публикуващата задача право да заяви OIDC самоличност и изпълнете npm publish без NPM_TOKEN. Ако хранилището и пакетът са публични, npm добавя provenance атестация автоматично.

Махнете стария токен от задачата преди първото издание по новата схема. npm CLI предпочита OIDC в подходяща среда, но може да използва традиционно удостоверяване, ако токенът още е наличен. Затова успешно публикуване със запазен NPM_TOKEN не показва кой път е сработил; отмяната на самия токен идва след успешно издание без него.

Свържете пакета с точния workflow

В настройките на пакета в npmjs.com отворете Trusted Publisher и изберете GitHub Actions. Въведете собственика и името на хранилището, а за workflow посочете само името на файла, например publish.yml, който се намира в .github/workflows/. Разрешете изрично npm publish сред Allowed actions, ако искате директно публикуване; разрешението за staged publishing само по себе си не го включва.

Сверете repository.url в package.json със същото GitHub хранилище, включително регистъра на буквите. Документацията на npm за trusted publishing изисква Node 22.14.0 или по-нова версия и npm CLI 11.5.1 или по-нова, а новата връзка трябва да завърши първото си успешно публикуване до 2 дни след създаването ѝ. Подгответе новата версия предварително: ако срокът изтече, връзката се изтрива и се създава отново.

Добавете минимален GitHub Actions workflow

Следният пример е за публичен пакет с package-lock.json и издания, задействани от тагове, започващи с v. Поставете съдържанието в .github/workflows/publish.yml. Компактният запис е валиден YAML синтаксис и запазва целия workflow в рамките на разрешените HTML елементи:

{"name":"Publish npm","on":{"push":{"tags":["v*"]}},"permissions":{"contents":"read","id-token":"write"},"jobs":{"publish":{"runs-on":"ubuntu-latest","steps":[{"uses":"actions/checkout@v6"},{"uses":"actions/setup-node@v6","with":{"node-version":"24","registry-url":"https://registry.npmjs.org","package-manager-cache":false}},{"run":"npm install -g npm@11"},{"run":"npm ci"},{"run":"npm run build --if-present"},{"run":"npm publish --access public"}]}}}

Ключовите условия са id-token: write и GitHub-hosted runner. Стъпката npm install -g npm@11 осигурява подходяща версия на CLI независимо от тази, включена в избрания Node образ. При първо публикуване на публичен пакет с обхват --access public задава нужната видимост; ако пакетът вече има установен достъп, съобразете командата с него. Добавете тестовете на проекта преди npm publish, ако workflow трябва да спира изданието при неуспех. Не е нужен флагът --provenance при trusted publishing с изпълнени условия за автоматична атестация.

Докажете миграцията, после отменете токена

1. Създайте trusted publisher, подгответе версия, която още не е публикувана, и сверете името на workflow с настройката в npm. При повторно използван workflow проверете кой файл го извиква: npm валидира извикващия workflow, а разрешението id-token: write е нужно и за извикващия, и за извиквания.
2. Премахнете NPM_TOKEN и NODE_AUTH_TOKEN за публикуване от env на задачата. Прегледайте общия env на workflow, използваните повторно задачи и .npmrc за записан write token. Оставен токен може да скрие неуспешна OIDC настройка чрез резервния път за удостоверяване.
3. Задействайте изданието и проверете дали npm publish завършва без предоставен write token. Това е проверка на реалното право за публикуване; npm whoami не проверява разрешенията на trusted publisher.
4. След успешното издание задайте в Settings → Publishing access „Require two-factor authentication and disallow tokens“. После отменете неизползвания automation token в npm и изтрийте съответния secret от GitHub. Ограничението за традиционните токени не спира разрешения OIDC издател.

Ако npm ci изтегля частни зависимости, дайте му отделен granular read-only токен само в env на стъпката за инсталиране. Оставете стъпката npm publish без него: trusted publishing удостоверява публикуването, а не изтеглянето на частни пакети. При ENEEDAUTH сверете първо името на workflow, id-token: write, вида runner и repository.url; записването на настройката в npm не проверява предварително дали тези полета съвпадат.

Кога има публикуване и кога има provenance

Успехът на OIDC публикуването и наличието на публична атестация са различни резултати. За GitHub Actions решаващи са видът на runner, видимостта на изходното хранилище и видимостта на пакета:

• GitHub-hosted runner, публично хранилище и публичен пакет: trusted publishing е поддържан и npm генерира provenance автоматично.
• GitHub-hosted runner, частно хранилище и публичен пакет: OIDC публикуването може да работи, но provenance не се генерира заради видимостта на хранилището.
• GitHub-hosted runner и частен пакет: OIDC може да обслужва публикуването, но не се генерира автоматична публична provenance атестация.
• Self-hosted runner: trusted publishing не се поддържа, независимо от видимостта на хранилището и пакета.

При публично хранилище и публичен пакет проверете и дали provenance не е изключен с provenance=false в .npmrc, чрез NPM_CONFIG_PROVENANCE или в publishConfig на package.json. При частно хранилище липсата на атестация е очаквана дори когато публикуването чрез OIDC е успешно. Тази разлика е важна при преглед на изданието: успешният workflow доказва, че пакетът е качен, а наличната атестация добавя проверима връзка към неговия произход.

Проверете връзката между пакета и изграждането

При създаването на provenance CI заявява OIDC самоличност, генерира временна ключова двойка и получава краткоживеещ сертификат от Fulcio. Техническото описание на npm provenance посочва, че npm проверява подписаната атестация, средата на runner, видимостта на хранилището и съвпадението между сертификата, repository.url и архива на публикувания пакет. Така произходът е свързан с конкретна версия и конкретно изграждане.

Отворете страницата на публикуваната версия в npm и прегледайте показаната provenance информация за изходното хранилище и workflow. За проверка на изтегления пакет го инсталирайте като зависимост и изпълнете npm audit signatures в проекта; указанията на npm за provenance посочват тази команда за проверка на атестациите на инсталирани пакети. Проверимият произход показва откъде и как е изграден пакетът, но не оценява дали самият код е безопасен.

Прочетете също:

• Агенти на OpenAI публикуваха 53 потребителски изображения онлайн
• Calendly или Microsoft Bookings: платеният пакет може вече да е купил избора