npm stage-only 토큰: 배포 자동화와 최종 승인을 나눌 때 남겨야 할 증거
CI가 패키지를 만들 수 있는 권한과 그 패키지를 사용자에게 공개할 권한을 분리하면, 릴리스의 마지막 책임이 더 선명해집니다. 하지만 승인 버튼 하나를 추가했다고 공급망 위험이 사라지는 것은 아닙니다. 승인자가 무엇을 확인하는지부터 정해야 합니다.
GitHub는 9월 18일 npm granular access token에 stage-only 쓰기 권한을 선택할 수 있다고 발표했습니다. 자동화는 버전을 검토 대기 상태로 제출하고, 유지관리자가 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 이상이 포함됩니다. 실제 이전 전에는 최신 문서를 다시 확인하고 사용하는 runner의 버전을 점검해야 합니다.
우선 영향이 작은 패키지 한 개에서 토큰 범위를 제한하고 staging 제출, 유지관리자 검토, 공개 결과 확인까지 연습하는 방안을 권합니다. 실패 시 곧바로 넓은 권한의 기존 토큰으로 우회하도록 만들면 분리한 경계가 무의미해집니다. 승인 지연도 정상 상태로 처리할 수 있어야 합니다.
trusted publishing과 비교할 질문
npm은 OIDC를 사용하는 trusted publishing도 제공합니다. 지원되는 CI 환경과 팀의 승인 방식에 맞는지 살펴보는 것이 먼저이며, stage-only 토큰을 모든 팀의 최종 해법으로 일반화할 이유는 없습니다. 토큰을 계속 써야 하는 자동화라면 단계적으로 옮길 선택지가 생긴 것으로 읽을 수 있습니다.
공식 발표는 2027년 1월을 bypass-2FA 토큰의 직접 공개 제거 목표로 안내합니다. 확정된 모든 구현 세부사항을 추측하기보다 대상 워크플로 목록과 이전 담당자를 지금 정리하는 편이 실용적입니다. 일정 변경 여부는 이후 공식 공지를 확인해야 합니다.
도입 여부를 결정할 때
이 글은 커뮤니티의 광범위한 합의나 실제 사고 감소율을 주장하지 않습니다. 신규 기능의 공식 동작을 바탕으로 검토 가능한 운영 절차를 제안한 것입니다. 자동화가 맡을 일과 사람이 확인할 일이 무엇인지 설명할 수 있는지가 도입 판단의 출발점입니다.
오늘 할 수 있는 작업은 현재 릴리스 토큰을 쓰는 곳을 찾고, 공개 완료를 판정하는 조건을 적고, 한 번의 승인에 필요한 증거를 정하는 것입니다. 권한 제한과 검토 품질을 함께 다뤄야 staging 단계가 실제로 도움이 됩니다.