npm stage-only 토큰: 자동 배포에 ‘검토 대기실’을 하나 더 두는 법

결론부터

npm 패키지를 CI에서 자동 배포하고 있다면 이번 주에 토큰 권한을 한 번 봐야 한다. 2026년 9월 18일 GitHub는 npm granular access token에 Read and write (stage only) 권한을 추가했다.GitHub 공식 이 토큰은 npm publish로 패키지를 바로 공개할 수 없다. 대신 CI가 npm stage publish로 패키지를 staging에 올리고, 유지보수자가 2FA로 검토·승인해야 실제 npm registry에 공개된다.GitHub 공식npm 공식

지금 읽어야 하는 이유는 단순히 npm 명령어가 하나 늘었기 때문이 아니다. npm은 2027년 1월을 목표로 2FA-bypass 토큰을 통한 직접 publish 제거를 예고했다.GitHub 공식 즉 “CI에 오래 사는 publish 토큰 하나 넣어두고 태그가 찍히면 바로 배포”하던 습관은 더 이상 오래 버티기 어렵다.

이 글에서 가져갈 문장은 하나다.

Trusted Publishing으로 바로 갈 수 없다면, stage-only 토큰은 자동 배포를 끊지 않으면서도 공개 직전에 사람의 승인 게이트를 넣는 현실적인 중간다리다.

기준 시점은 2026년 9월 23일이다. 아래 내용은 GitHub Changelog, npm staged publishing 문서, npm trusted publishers 문서를 대조해 정리했다.GitHub 공식npm 공식npm 공식

무엇이 바뀌었나

기존 npm 자동 배포는 보통 두 갈래였다. 하나는 CI 비밀값에 npm publish 토큰을 넣고 npm publish를 실행하는 방식이다. 빠르지만 토큰이 새거나 워크플로가 오작동하면 패키지가 바로 공개된다. 다른 하나는 OIDC 기반 Trusted Publishing이다. GitHub Actions, GitLab CI/CD, CircleCI 같은 지원 CI에서 짧게 사는 신원 토큰으로 npm에 publish한다.npm 공식

stage-only 토큰은 그 사이에 들어온다.

방식	CI가 할 수 있는 일	사람이 해야 하는 일	좋은 점	조심할 점
기존 publish 토큰	바로 npm publish	보통 없음	단순하고 빠르다	토큰 유출·실수 시 바로 공개된다
Trusted Publishing	OIDC로 npm publish 또는 npm stage publish	설정에 따라 다름	오래 사는 토큰을 없앤다	지원 CI·러너 제약이 있다
stage-only 토큰	npm stage publish	2FA로 approve	직접 공개 권한을 CI에서 뺀다	다른 write 권한은 남는다

GitHub Changelog의 핵심 문장은 분명하다. stage-only 토큰으로는 npm publish가 거부된다. 자동화에서 2FA 우회가 설정되어 있어도 직접 publish는 되지 않는다.GitHub 공식 대신 패키지는 staging area에 들어가고, maintainer가 CLI나 npmjs.com에서 staged package를 확인한 뒤 npm stage approve <stage-id> 또는 웹 UI로 승인한다.npm 공식

비유하면 자동문 앞에 작은 접수대를 둔 것이다. CI는 택배 상자를 건물 안에 들여놓을 수 있지만, 매장 진열대에 바로 올릴 수는 없다. 진열대에 올리는 일은 2FA를 가진 사람이 한다.

stage-only가 막아주는 것과 못 막는 것

stage-only 토큰이 막아주는 것은 “CI가 패키지를 바로 공개하는 일”이다. 이 차이는 작지 않다. 실수로 잘못된 tag를 만들었거나, 릴리스 job이 예상보다 넓은 조건에서 돌았거나, build 결과물을 사람이 한 번 더 보고 싶은 상황에서 staging은 숨 쉴 틈을 만든다.

하지만 이 토큰이 마법 방패는 아니다. GitHub는 stage-only 토큰도 다른 package write 권한을 유지한다고 명시했다. 예를 들어 dist-tag 이동이나 version deprecate 같은 작업은 여전히 조심해야 한다.GitHub 공식

그래서 stage-only 토큰을 “안전한 공개 버튼”으로 부르면 안 된다. 더 정확히는 “공개 버튼만 떼어낸 write 토큰”이다. 토큰 보관, 권한 범위, rotation, workflow 조건 검사는 그대로 필요하다.

실제 전환은 어떻게 하나

npm 문서 기준으로 staged publishing은 세 단계다.npm 공식

1. 패키지를 staging에 올린다.
2. staged package를 확인한다.
3. 2FA로 approve해서 공개한다.

기본 명령은 단순하다.

# CI 또는 릴리스 워크플로에서
npm stage publish

# 유지보수자 로컬 또는 인증된 환경에서
npm stage list
npm stage view <stage-id>
npm stage download <stage-id>
npm stage approve <stage-id>

전환 전에 확인할 조건도 있다. staged publishing은 기존 npm package에 쓸 수 있고, 새 패키지를 처음 만들 때는 stage할 수 없다. publish access가 있어야 하고, npm 계정에 2FA가 켜져 있어야 한다. 도구 버전은 npm CLI 11.15.0 이상, Node.js 22.14.0 이상이 필요하다.npm 공식

CI 설정은 대략 이렇게 바뀐다.

# 예시: publish 대신 stage publish로 바꾸는 최소 변경
- run: npm ci
- run: npm test
- run: npm run build --if-present
- run: npm stage publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_STAGE_ONLY_TOKEN }}

그리고 release checklist에는 사람이 볼 항목을 넣는다.

확인 항목	봐야 하는 이유
tarball 파일 목록	실수로 테스트 파일, 비밀 파일, 큰 산출물이 들어갔는지 본다
package version	기존 버전과 충돌하거나 잘못 증가하지 않았는지 본다
dist-tag 계획	latest, next, beta가 의도한 흐름인지 본다
changelog와 git tag	사용자가 읽을 변경 설명과 실제 코드가 맞는지 본다
provenance/CI 로그	어디서 빌드됐고 어떤 commit인지 추적할 수 있는지 본다

Trusted Publishing과 stage-only는 경쟁 관계가 아니다

장기적으로 가장 좋은 방향은 오래 사는 publish 토큰을 줄이는 것이다. npm Trusted Publishing은 OIDC로 CI와 npm 사이에 신뢰 관계를 만들고, 장기 npm 토큰 없이 publish할 수 있게 한다.npm 공식 문서도 이 방식을 “long-lived write tokens”의 노출 위험을 줄이는 방법으로 설명한다.npm 공식

그렇다면 stage-only 토큰은 왜 필요할까. 모든 프로젝트가 당장 Trusted Publishing으로 갈 수 없기 때문이다. npm 문서에 따르면 Trusted Publishing은 현재 GitHub Actions의 GitHub-hosted runners, GitLab.com shared runners, CircleCI cloud를 지원하며 self-hosted runners는 아직 지원되지 않는다.npm 공식 회사 네트워크, 자체 runner, 복잡한 release job, 여러 registry를 함께 쓰는 프로젝트라면 전환에 시간이 걸린다.

내가 고른 판단표는 이렇다.

상황	추천
GitHub-hosted runner에서 일반적인 공개 npm package를 배포한다	Trusted Publishing 우선 검토
직접 publish는 없애고 싶지만 self-hosted runner나 내부 제약이 있다	stage-only 토큰으로 먼저 완충
보안상 사람이 tarball을 꼭 확인해야 한다	Trusted Publishing + npm stage publish 조합
배포가 너무 잦고 사람이 매번 승인할 수 없다	OIDC 직접 publish + 강한 테스트/환경 보호, 단 고위험 패키지는 예외 검토
brand-new package를 처음 공개한다	staged publishing만으로는 부족하므로 초기 publish 절차 별도 설계

중요한 건 “자동화냐 수동이냐”의 이분법이 아니다. 어느 지점까지는 기계가 반복 일을 하고, 어느 지점부터는 사람이 되돌리기 어려운 결정을 확인할지 정하는 문제다.

실무 체크리스트

오늘 할 일은 크지 않다. 패키지를 많이 운영하는 팀이라면 아래만 해도 절반은 정리된다.

• npm publish workflow에서 npm publish, npm stage publish, Trusted Publishing 사용 여부를 목록화한다.
• npm granular token 중 2FA bypass 또는 publish write 권한을 가진 토큰을 찾는다.
• self-hosted runner 때문에 OIDC 전환이 막힌 프로젝트를 따로 표시한다.
• 기존 패키지 중 “실수로 공개되면 영향이 큰” 패키지부터 stage-only 토큰을 시험한다.
• 승인자가 볼 tarball checklist를 release 문서에 추가한다.
• npm stage download <stage-id>로 실제 tarball을 열어보는 연습을 한 번 한다.
• dist-tag 이동과 deprecate 권한은 여전히 write risk라는 점을 secret 관리 문서에 적는다.

특히 작은 오픈소스 패키지는 “어차피 나 혼자 maintainer인데?”라고 넘기기 쉽다. 하지만 혼자일수록 더더욱 자동화가 실수했을 때 말릴 사람이 없다. stage-only는 누군가의 승인을 추가하는 장치이기도 하지만, 미래의 내가 잠깐 멈춰 보는 장치이기도 하다.

내가 배운 점

이번 변화에서 흥미로운 점은 npm이 자동화를 줄이라고 말하는 게 아니라, 자동화의 마지막 권한을 작게 쪼개고 있다는 것이다. CI가 빌드하고, 테스트하고, 패키지를 준비하는 일은 계속 자동화한다. 다만 “세상에 공개한다”는 순간만 별도 권한과 2FA로 분리한다.

AI 코딩 에이전트와 배포 자동화가 빨라질수록 이 패턴은 더 중요해진다. 에이전트가 changelog를 쓰고, version을 올리고, release PR을 만들 수는 있다. 하지만 registry에 공개되는 순간은 여전히 감사 가능한 게이트가 필요하다. 빠른 자동화일수록 멈춤 버튼이 더 선명해야 한다.

독자가 오늘 적용할 1가지

가장 위험한 npm package 하나를 고르고, 그 release workflow에서 npm publish가 어디서 실행되는지 확인한다. 그 다음 선택지는 두 개다. OIDC Trusted Publishing으로 옮길 수 있으면 그쪽을 먼저 본다. 당장 어렵다면 stage-only 토큰을 만들고 npm stage publish로 바꿔, 다음 릴리스에서 staged package를 직접 내려받아 검토해본다.

FAQ

stage-only 토큰을 쓰면 npm publish가 정말 막히나?

GitHub Changelog는 stage-only 토큰으로 직접 npm publish를 시도하면 npm이 거부한다고 설명한다. 자동화용 2FA bypass 설정이 있어도 직접 publish 권한은 주어지지 않는다.GitHub 공식

staged publishing은 새 npm package에도 쓸 수 있나?

npm 문서 기준으로 staged publishing은 이미 npm registry에 존재하는 패키지에 필요하다. 새 패키지를 처음 만드는 경우에는 별도 초기 publish 절차를 설계해야 한다.npm 공식

Trusted Publishing을 쓰면 stage-only는 필요 없나?

항상 그렇지는 않다. Trusted Publishing은 오래 사는 토큰을 없애는 쪽이고, staged publishing은 공개 전 승인 단계를 넣는 쪽이다. npm 문서도 Trusted Publishing에서 npm stage publish를 사용할 수 있다고 설명한다.npm 공식npm 공식

stage-only 토큰은 안전한 토큰인가?

직접 publish를 막는다는 점에서는 더 안전하지만, 여전히 package write 권한을 가진 비밀값이다. GitHub는 dist-tag 이동과 version deprecate 같은 write 권한이 남는다고 경고한다.GitHub 공식

어떤 프로젝트부터 바꾸면 좋나?

사용자가 많은 공개 패키지, 자동 release가 잦은 패키지, self-hosted runner 때문에 OIDC 전환이 늦어지는 패키지부터 보는 것이 좋다. 영향이 큰 패키지일수록 “바로 공개”보다 “staging 후 승인”의 가치가 커진다.

타깃 유입 키워드

• npm stage-only token
• npm staged publishing
• npm stage publish approve
• npm trusted publishing OIDC
• npm 2FA bypass token January 2027
• CI/CD npm supply chain security

출처