npm 첫 배포도 CI에서 준비하고, 승인 뒤 공개할 수 있다

새 패키지를 만들기 위한 첫 수동 배포가 줄어든다

새 라이브러리의 첫 릴리스를 준비할 때도 CI가 업로드를 맡고 사람이 공개 시점을 결정할 수 있다. npm이 10월 2일 발표한 변경으로 npm stage publish는 레지스트리에 없는 패키지도 생성한다. 로컬 로그인 세션이나 세분화된 액세스 토큰을 사용하며, staging만 허용하는 stage-only 토큰도 지원한다.

지원 대상은 공개 scoped·unscoped 패키지와 비공개 scoped 패키지다. 패키지를 만든 뒤에는 설정을 관리하고 Trusted Publishing을 연결할 수 있다. 따라서 이번 변경은 처음부터 등록되지 않은 OIDC 연결로 배포할 수 있다는 의미가 아니라, 첫 패키지 생성 자체를 승인 대기 흐름에 넣을 수 있다는 변화다.

0.0.0-stage는 검토 중인 코드가 공개됐다는 뜻이 아니다

처음 만드는 공개 패키지에서는 승인 전에 0.0.0-stage라는 자리표시자 버전이 보일 수 있다. npm의 단계별 안내는 이 자리표시자와 실제로 제출한 staged 버전을 구분한다. 승인 대기 버전의 내용은 관리자가 승인하기 전까지 공개되지 않는다.

예를 들어 공개하려는 버전이 1.0.0이라면, 패키지 페이지가 생겼다는 사실만으로 그 코드의 공개가 끝난 것은 아니다. 반대로 staging을 이용한다고 패키지의 존재 자체까지 숨겨지는 것도 아니다. 배포 완료 여부는 이름이 검색되는지가 아니라 목표 버전의 승인 상태로 판단해야 한다.

파일을 올린 다음, 배포할 묶음을 확인한다

staged publishing에는 npm CLI 11.15.0 이상과 Node.js 22.14.0 이상이 필요하다. 패키지를 게시할 권한과 계정의 2단계 인증도 준비해야 한다. 업로드 단계에서는 2단계 인증을 요구하지 않고, 실제 승인 단계에서 인증한다.

공개할 패키지 디렉터리에서의 최소 흐름은 다음과 같다. STAGE_ID는 목록에 표시된 실제 ID로 바꾼다. 마지막 명령은 파일을 확인하고 공개를 결정한 관리자가 실행하는 단계다.

npm stage publish --access public
npm stage list
npm stage view STAGE_ID
npm stage download STAGE_ID

# 검토 후 공개할 때 실행
npm stage approve STAGE_ID

CLI 명령 문서의 download는 검토할 tarball을 내려받는다. 웹에서는 npmjs.com의 Staged Packages 탭에서 대상을 열고 승인할 수 있다. CLI와 웹 어느 쪽으로 승인해도 2단계 인증이 필요하다.

OIDC는 누가 올리는지, staging은 언제 공개하는지를 정한다

Trusted Publishing은 CI 작업의 OIDC 신원을 이용하는 인증 방식이다. 여기에 staging을 결합하면 CI가 파일을 제출한 뒤 관리자가 공개를 승인한다. 새 연결의 설정에서는 staging과 직접 npm publish 허용 여부를 구분할 수 있다.

사람의 승인을 배포 절차로 삼으려면 CI 명령만 바꾸는 데서 끝내지 말고 그 연결에 직접 publish 권한이 남아 있는지도 살펴야 한다. staging을 한 번 썼다는 사실이 다른 직접 배포 경로까지 막지는 않는다.

비공개 배포를 준비할 때는 또 다른 구분이 필요하다. package.json의 "private": true는 게시 금지 표시여서 staging도 거부된다. 비공개 scoped 패키지의 접근 범위는 --access restricted로 지정한다. 공개 예시의 옵션을 그대로 쓰지 않아야 한다.

자주 묻는 질문