-
[npm][보안] Trusted Publishing을 설정했는데 registry provenance 화면이 비어 보일 때 OIDC publish인지 token fallback인지부터 다시 보나기타개발지식/풀스택개발 2026. 7. 19. 09:22
IT 리서치 노트
[npm][보안] Trusted Publishing을 설정했는데 registry provenance 화면이 비어 보일 때 OIDC publish인지 token fallback인지부터 다시 보나
npm에서 Trusted Publishing을 설정해 두었는데도 특정 version의 registry provenance 화면이 비어 보이면 꽤 헷갈린다. 2026년 7월 19일 기준 npm 공식 문서를 다시 보면 provenance 자동 생성은 단순히 설정을 켜 두는 문제보다, 실제 publish가 OIDC 경로를 탔는지와 public repository·public package 조건을 모두 만족했는지가 중요하다. 이 글은 registry provenance 화면이 비어 보일 때 무엇부터 다시 나눠 봐야 하는지 정리한 것이다.
1. 개요
결론부터 말하면 registry provenance가 비어 보일 때는 UI 문제부터 의심하기보다 publish path를 먼저 본다. npm 문서는 CLI가 OIDC를 먼저 시도하고 안 되면 token으로 fallback할 수 있다고 설명하고, provenance 자동 생성은 OIDC publish, public repository, public package 조건이 모두 맞아야 한다고 설명한다.
그래서 가장 빠른 점검 순서는 '이번 publish가 실제로 OIDC였는가'와 '공개 repo·공개 package 조건이 맞는가'를 먼저 분리하는 것이다. 그 다음에야 registry page와 후속 audit 자료를 보는 편이 덜 헤맨다.
2. 어디서 실제로 막히는가
실무에서 자주 막히는 지점은 세 가지다. 첫째, trusted publisher 설정이 있으니 모든 publish가 자동으로 provenance를 만들었다고 생각한다. 둘째, publish는 성공했으니 provenance 배지도 UI가 늦게 뜨는 정도라고 넘긴다. 셋째, 실제로는 token fallback이 일어났는데 CI 설정이 맞았다고 믿고 publish 로그를 안 본다.
하지만 npm 문서는 CLI가 OIDC 환경을 자동 감지하고, 그렇지 않으면 traditional token 경로로 fallback할 수 있다고 말한다. 또 provenance 자동 생성은 trusted publishing 자체만으로 끝나지 않고 public repository와 public package 조건이 함께 필요하다고 적고 있다. 이 두 문장을 같이 보면 publish 성공과 provenance 생성은 같은 체크가 아니라는 점이 보인다.
- 증상: Trusted Publishing을 켰는데 registry 배지가 안 보인다.
- 실패: 설정 존재와 실제 publish path를 같은 것으로 본다.
- 막힘: token fallback 여부를 publish 로그 밖에서 추정만 한다.
- 누락: public repository와 public package 조건을 함께 적지 않는다.
질문 먼저 볼 문서 포인트 왜 먼저 보나 이번 publish가 OIDC였나 trusted publishers fallback 설명 설정만 맞고 실제 경로는 token일 수 있다 자동 provenance 생성 조건을 만족했나 OIDC + public repo + public package 세 조건 중 하나라도 빠지면 기대가 어긋난다 registry page가 비어 보이는 이유가 무엇인가 viewing provenance 문서 version에 provenance가 붙은 경우에만 상세 화면이 의미 있다 3. 실무에서 적용하는 순서
가장 짧은 점검 순서는 다섯 단계다. 먼저 publish 로그와 runner 환경에서 OIDC publish가 실제로 감지됐는지 본다. 두 번째로 repository와 package가 둘 다 public인지 확인한다. 세 번째로 provenance가 기대되는 version인지 정리한 뒤 registry page를 본다. 네 번째로 필요하면
npm publish --provenance또는 관련 config를 어떻게 사용했는지 적는다. 다섯 번째로 그 다음에야 release audit 자료와 소비자 검증 단계를 붙인다.- 이번 publish가 OIDC publish였는지부터 확인한다.
- token fallback 가능성을 publish 경로에서 분리한다.
- public repository와 public package 조건을 다시 본다.
- registry page는 해당 version에 provenance가 있어야 의미가 있음을 전제로 읽는다.
- 그 다음에야 audit 자료와 후속 검증을 붙인다.
이 순서를 고정해 두면 registry UI를 새로고침하다가 시간을 쓰는 일이 줄어든다. provenance 빈 화면은 대부분 '표시만 늦다'보다 '이번 publish path가 provenance 생성 조건을 탔는가'의 문제로 좁혀지는 경우가 많다.
publish checks: 1. OIDC publish 확인한다 2. token fallback 여부 확인한다 3. public repo 확인한다 4. public package 확인한다 5. registry provenance page 조회한다4. 공식 문서와 예시 화면으로 확인하기
첫 화면은 npm trusted publishers 문서의 핵심 문장이다. npm CLI는 OIDC 환경을 자동 감지해 먼저 쓰고, 안 되면 전통적인 token 인증으로 fallback할 수 있다고 적고 있다.
즉 trusted publishing을 설정해 두었다고 해서 모든 publish가 provenance가 붙는 경로를 탄다고 자동 보장되지는 않는다. registry 화면이 비어 보인다면 먼저 이번 배포가 실제로 OIDC publish였는지부터 나눠야 한다.
두 번째 화면은 provenance 자동 생성 조건이다. 문서는 trusted publishing, public repository, public package 세 조건이 모두 충족될 때만 자동 생성이 적용된다고 못 박고 있다.
그래서 registry provenance가 비어 있으면 token fallback만 볼 것이 아니라 repo와 package 공개 조건도 같이 확인해야 한다. 세 조건 중 하나라도 빠지면 기대한 배지가 안 나타날 수 있다.
세 번째 화면은 generating provenance statements 문서다. provenance attestation은 소스 코드와 build instruction 링크를 공개적으로 연결하는 방식이라고 설명한다.
즉 registry 상세 화면이 비어 보인다는 것은 단순 UI 문제가 아니라, publish 경로가 provenance attestation을 만들 조건을 만족했는지의 문제일 가능성이 크다. publish path 자체를 다시 확인하는 쪽이 먼저다.
네 번째 화면은 npm registry provenance 보기 문서다. provenance가 있는 패키지에서는 어디서 어떻게 publish됐는지 검증할 수 있다고 설명한다.
따라서 이 화면이 비어 있다는 것은 UI 캡처 이슈보다 '이번 version이 provenance와 함께 올라왔나'라는 publish 결과 해석 문제로 봐야 한다. publish 경로를 다시 자르지 않으면 계속 표면 증상만 보게 된다.
실무에서는 provenance 빈 화면 문제를 네 칸으로 나눠 보면 빠르다. OIDC publish 여부, token fallback 여부, repo/public 조건, registry page 확인 순서를 한 표에 두는 편이 좋다.
이미 --provenance와 audit signatures 순서 글을 읽었다면, 이번 글은 그보다 앞단의 publish path 확인이다. 또 release audit 체크리스트 글에 넣기 전 사전 분기라고 보면 된다.
마지막 화면은 publish 기록에 남기면 좋은 runbook 예시다. provenance 빈 화면 문제는 결국 어떤 인증 경로로 어떤 가시성 조건에서 올렸는지를 한 줄로 남겨 두는 쪽이 가장 빠르다.
이 정도 기록만 있어도 token fallback, public repo 조건, registry page 확인을 순서대로 재현할 수 있다. 나중에 audit signatures나 include-attestations를 붙일 때도 앞단 조건을 분리해 읽기 쉬워진다.
5. 주의사항과 리스크
첫 번째 리스크는 trusted publisher 설정이 있다는 사실만 보고 실제 publish path를 확인하지 않는 것이다. 두 번째는 token fallback이 있었는데도 provenance 배지가 안 뜨는 원인을 registry UI 쪽으로만 돌리는 것이다. 세 번째는 repo나 package 공개 조건을 문서화하지 않아 다음 릴리스 때 같은 혼선을 반복하는 것이다.
운영 전에는 publish record에 OIDC 감지 여부, token fallback 여부, repo visibility, package visibility를 같이 남기는 편이 좋다. 그래야 provenance attestation 누락 글이나 release audit 글과도 자연스럽게 이어진다.
- 설정 존재와 실제 publish path를 같은 것으로 보지 않는다.
- token fallback 여부를 publish 기록에 남긴다.
- public repo·public package 조건을 version 기록에 함께 적는다.
6. 결론
Trusted Publishing을 켰는데 registry provenance 화면이 비어 보인다면 가장 먼저 다시 볼 것은 UI가 아니라 publish path다. 이번 publish가 실제 OIDC 경로였는지, 그리고 public repository·public package 조건을 만족했는지를 먼저 분리해야 한다.
관련 흐름으로는 provenance attestation 누락 글, release audit 체크리스트 글, --provenance와 audit signatures 글을 같이 보면 publish path와 사후 검증을 한 줄로 정리하기 쉽다.
이번에 본 token fallback 분기를 지나 version과 package visibility까지 같이 나눠 보고 싶다면 npm audit signatures는 통과하는데 registry provenance 화면이 비어 있을 때 무엇부터 다시 보는지 정리한 후속 글을 같이 읽으면 좋다.
7. 참고 링크
'기타개발지식 > 풀스택개발' 카테고리의 다른 글
