[npm][보안] staged publishing을 붙인 뒤 trust relationship 권한을 allow-publish와 allow-stage-publish 중 어디까지 열어야 하나

IT 리서치 노트

[npm][보안] staged publishing을 붙인 뒤 trust relationship 권한을 allow-publish와 allow-stage-publish 중 어디까지 열어야 하나

npm trusted publishing에 staged publishing을 붙인 뒤에도 어떤 팀은 여전히 CI가 바로 live publish 하길 원하고, 어떤 팀은 모든 자동 배포를 review와 2FA가 필요한 stage-only 흐름으로 막고 싶어 한다. 2026년 8월 11일 기준 npm 공식 문서를 다시 보면 trust relationship 권한은 이제 command 단위로 나뉘고, trusted publisher에는 allow-publish와 allow-stage-publish를 따로 줄 수 있다. 이 글은 staged publishing을 붙인 뒤 trust relationship 권한을 어디까지 여는 편이 release governance와 supply-chain 운영에 맞는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 review와 2FA를 모든 릴리스에 강제하고 싶다면 allow-stage-publish만 먼저 여는 편이 맞다. 긴급 핫픽스까지 CI direct publish가 꼭 필요할 때만 allow-publish를 추가한다. 두 권한은 같은 trusted publisher의 세부 옵션이지, 같은 의미의 중복 플래그가 아니다.

즉 이 문제는 'trusted publisher를 쓸지 말지'보다 'trusted publisher가 어떤 명령까지 실행해도 되는지'를 정하는 층에 가깝다. 권한 선택이 governance를 결정한다.

2. 어디서 실제로 막히는가

현장에서 흔한 혼선은 세 가지다. 첫째, staged publishing을 켰으니 CI가 자동으로 live publish를 못 한다고 오해한다. 둘째, trusted publisher를 붙였다는 이유만으로 allow-publish까지 열린 줄 안다. 셋째, 권한 플래그를 바꾼 시각과 실제 provenance detail 확인 시각을 같이 안 남겨 stage-only 지연과 misconfiguration을 구분하지 못한다.

npm trusted publishers 문서는 더 강한 보안을 원하면 stage-only permissions를 쓰라고 직접 권장하고, npm stage CLI 문서는 trust relationship permission이 granular command permissions라고 적는다. npm trust CLI 문서는 allow-publish와 allow-stage-publish를 별도 permission flag로 설명한다. 이 셋을 같이 읽으면 permission choice 자체가 릴리스 프로세스 설계라는 점이 분명해진다.

• 증상: CI는 성공했는데 package가 바로 live registry에 안 뜬다.
• 실패: staged publishing을 켜 놓고 allow-publish까지 열어도 되는지 메모가 없다.
• 막힘: trust relationship 존재와 command permission 범위를 같은 말로 쓴다.
• 누락: provenance detail 확인 시각을 권한 변경 시각과 분리해서 안 남긴다.

증상	먼저 볼 곳	판단 기준
자동 배포가 live publish까지 안 간다	trust permission	allow-stage-publish만 열려 있는지 본다
review 없이 바로 registry에 올라간다	allow-publish 여부	직접 publish까지 허용된 상태인지 본다
권한은 맞는 것 같은데 UI가 헷갈린다	provenance detail	실제 publish path를 결과 화면으로 닫는다

3. 실무에서 적용하는 순서

실무에서는 네 단계가 가장 짧다. 먼저 패키지가 무조건 review를 거쳐야 하는지, 긴급 direct publish가 필요한지 정한다. 두 번째로 그 기준에 맞춰 allow-stage-publish만 줄지, allow-publish도 같이 열지 선택한다. 세 번째로 권한 플래그를 메모에 적는다. 마지막으로 실제 릴리스 뒤 provenance detail을 열어 stage 경로인지 direct publish 경로인지 닫는다.

1. review 강제 여부를 먼저 정한다.
2. stage-only인지 direct publish 허용인지 고른다.
3. trust permission 플래그를 release note 첫 줄에 적는다.
4. publish 뒤 provenance detail로 실제 경로를 닫는다.

npm trust github --allow-stage-publish
# 필요 시에만
npm trust github --allow-publish --allow-stage-publish

이 순서를 지키면 릴리스 속도 요구와 보안 요구를 같은 문서 안에서 분리할 수 있다. stage-only로 시작해도 나중에 allow-publish를 추가하는 쪽이 반대보다 되돌리기 쉽다.

4. 공식 문서와 예시 화면으로 확인하기

첫 공식 화면은 npm trusted publishers 문서의 stage-only permissions 구간이다. npm은 더 강한 보안을 원하면 자동 publish 대신 stage-only 권한을 주라고 적고 있다.

npm은 trusted publisher에 stage-only 권한을 주면 모든 자동 배포를 review와 2FA가 필요한 staged flow로 강제할 수 있다고 설명한다.

즉 allow-publish와 allow-stage-publish는 같은 체크박스가 아니다. release 속도와 approval 경계가 달라지는 별도 권한층이다.

두 번째 자료는 npm stage CLI 문서다. 이 문서는 trust relationship 권한이 granular command permissions로 바뀌었고, short-lived token은 npm stage publish와 npm publish 범위로 제한된다고 설명한다.

staged publishing을 쓰면 trust relationship 권한도 command 단위로 쪼개서 봐야 한다.

이 구조를 놓치면 CI가 어느 명령까지 허용됐는지와 registry 승인 절차를 한 문제로 뭉개게 된다. 운영 메모에는 command 권한을 먼저 적는 편이 좋다.

세 번째 자료는 npm trust 권한 플래그다. npm은 trust relationship 생성 시 최소 하나 이상의 permission flag가 필요하고, allow-publish와 allow-stage-publish를 별도로 준다고 못 박는다.

npm trust는 allow-publish와 allow-stage-publish를 서로 다른 permission flag로 다룬다.

따라서 'trusted publisher를 붙였다'는 문장만으로는 부족하다. 어떤 package에 어느 flag를 열었는지 남겨야 다음 릴리스 회고가 짧아진다.

네 번째 공식 화면은 staged publishing 개요다. npm은 trusted publishing을 쓰는 CI라도 live publish 전에 maintainer review와 2FA를 둘 수 있다고 설명한다.

staged publishing은 CI 자동화와 maintainer review를 일부러 분리하는 흐름이다.

이 설명은 stage-only 권한을 언제 쓰는지가 release governance 문제라는 뜻이다. 속도보다 승인 경계가 중요한 패키지라면 allow-stage-publish만 열어도 된다.

다섯 번째 자료는 provenance detail 확인 지점이다. 권한 선택이 끝이 아니라 publish 후 registry provenance 화면으로 실제 경로를 검증해야 한다.

permission 선택 뒤에는 package provenance detail에서 실제 publish 경로를 닫아야 한다.

즉 allow-publish를 열었든 stage-only를 열었든 결과 검증은 provenance detail에서 한다. 권한 메모와 결과 메모를 따로 두는 이유가 여기에 있다.

실무에서는 패키지 성격에 따라 권한층을 먼저 나누는 편이 낫다. 긴급 핫픽스가 있는 공개 패키지와, 무조건 review를 거쳐야 하는 조직 패키지를 같은 표에 넣었다.

allow-publish와 allow-stage-publish를 고르는 권장 기준표다.

이미 npm trust와 웹 설정 글, staged publish release record 글을 읽었다면 이번 표는 그 위쪽 permission 결정층이다.

마지막 자료는 release 메모 예시다. 핵심은 trusted publisher 존재 여부보다 command permission과 실제 publish path를 함께 적는 것이다.

staged publishing trust permission을 기록하는 메모 예시다.

이 정도 메모가 있으면 package page 경고나 provenance detail 지연이 생겨도 어느 단계까지는 정상인지 바로 복기할 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 stage-only가 필요한 패키지에 allow-publish를 기본값처럼 열어 두는 것이다. 두 번째는 trusted publisher가 있다는 이유로 command permission 범위까지 자동으로 안전하다고 가정하는 것이다. 세 번째는 권한 플래그 변경 시각과 provenance detail 확인 시각을 같이 안 남겨 지연과 misconfiguration을 구분하지 못하는 것이다.

특히 supply-chain audit에서는 '누가 publish할 수 있나'만큼 '어느 명령까지 자동으로 실행되나'가 중요하다. release note에는 최소한 trust permission과 실제 publish path가 같이 있어야 한다.

• stage-only가 기본값이면 review 우회 가능성이 줄어든다.
• allow-publish는 direct live publish 필요성이 확인됐을 때만 연다.
• 결과 검증은 provenance detail에서 닫는다.

6. 결론

staged publishing을 붙인 뒤 trusted publisher 권한을 정할 때는 allow-stage-publish를 기본 보수값으로 두고, direct live publish가 정말 필요한 패키지에만 allow-publish를 추가하는 편이 맞다. permission choice가 곧 release governance다.

• 기본값은 stage-only가 안전하다.
• 긴급 direct publish가 필요할 때만 allow-publish를 추가한다.
• publish 결과는 provenance detail로 확인한다.

7. 참고 링크

1. https://docs.npmjs.com/trusted-publishers/
2. https://docs.npmjs.com/cli/v12/commands/npm-stage/
3. https://docs.npmjs.com/cli/v12/commands/npm-trust/
4. https://docs.npmjs.com/staged-publishing/
5. https://docs.npmjs.com/viewing-package-provenance/