[npm][보안] linked source repository 경고를 고칠 때 repository.url, workflow filename, 새 버전 재배포를 어떤 순서로 다시 맞추나

IT 리서치 노트

[npm][보안] linked source repository 경고를 고칠 때 repository.url, workflow filename, 새 버전 재배포를 어떤 순서로 다시 맞추나

npm provenance 화면에서 linked source repository 경고가 뜨면 많은 팀이 registry UI부터 계속 새로고침한다. 하지만 2026년 7월 26일 기준 npm 공식 문서를 다시 보면 recovery의 핵심은 repository.url exact match, publish 위치와 visibility, trusted publisher의 repository와 workflow filename 정합성, 그리고 새 버전 재배포 순서다. 이 글은 경고를 실제로 고칠 때 무엇부터 다시 맞추고 어떤 시점에 새 버전을 publish하고 어디서 재검증해야 같은 문제가 반복되지 않는지 정리한다.

목차

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

1. 개요

결론부터 말하면 linked source repository 경고 복구는 metadata, publish config, trusted publisher, republish, recheck 순서로 가는 편이 가장 빠르다. 먼저 package.json의 repository.url을 맞추고, 그다음 repository visibility와 publish 위치를 확인하고, 이어서 trusted publisher의 repo와 workflow filename을 다시 본 뒤, 마지막에 새 버전으로 재배포하고 registry UI를 재확인한다.

즉 recovery의 핵심은 같은 버전을 기다리는 것이 아니라 고친 설정으로 새 버전을 만드는 일이다. 이 순서를 고정해 두면 provenance incident 허브 글에서 linked source branch를 실제 복구 runbook으로 바로 내릴 수 있다.

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

현장에서 흔한 실패는 네 가지다. 첫째, 경고를 보고도 repository.url을 나중에 확인한다. 둘째, rename이나 transfer 뒤 repository URL만 고치고 실제 publish가 어느 repo와 workflow에서 나가는지는 안 본다. 셋째, trusted publisher 설정이 저장될 때 검증되지 않는다는 사실을 잊고 workflow filename drift를 놓친다. 넷째, 고친 뒤에도 같은 버전 페이지를 새로고침하며 해결을 기대한다.

npm 문서는 recovery 단서를 나눠 둔다. trusted publishers 문서는 repository.url exact match와 repository, workflow filename 설정 오류가 publish 시점에야 드러날 수 있다고 설명한다. generating provenance statements 문서는 public repository match를 prerequisite로 적고, viewing package provenance 문서는 publish 뒤 provenance detail과 verify 흐름을 다시 확인하게 한다. 즉 linked source recovery는 UI가 아니라 설정과 재배포의 순서 문제다.

특히 rename이나 transfer 뒤에는 세 층이 동시에 틀어질 수 있다. package.json은 옛 repo URL을 가리키고, trusted publisher는 옛 repository나 workflow filename을 가리키고, registry는 이미 publish된 옛 버전을 보여 준다. 이 상태에서 verify만 다시 돌리면 source link warning이 계속 남아도 이상하지 않다.

• 증상: provenance detail은 열리는데 linked source repository warning이 남는다.
• 실패: repository.url exact match를 첫 단계로 두지 않는다.
• 막힘: trusted publisher의 repo와 workflow filename drift를 안 본다.
• 누락: 새 버전 재배포 없이 같은 version 페이지를 계속 새로고침한다.

어긋날 수 있는 층	먼저 볼 값	왜 중요하나
package metadata	repository.url	source link lookup의 가장 직접적인 입력값이다
publish prerequisites	public repository, publish 위치, casing	provenance와 source link 조건이 동시에 맞아야 한다
trusted publisher config	repository, workflow filename	저장 시 검증되지 않아 drift를 놓치기 쉽다

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

가장 짧은 recovery는 다섯 단계다. 1단계에서 package.json의 repository.url을 실제 repo URL과 대조한다. 2단계에서 publish 위치와 repo visibility, casing을 확인한다. 3단계에서 trusted publisher의 repository와 workflow filename을 다시 본다. 4단계에서 고친 설정으로 새 버전을 publish한다. 5단계에서 registry UI와 verify 결과를 새 버전 기준으로 저장한다.

1. package.json을 열어 repository.url을 실제 repo URL과 비교한다.
2. public repository 조건과 publish 위치를 확인한다.
3. trusted publisher 설정의 repository와 workflow filename을 조회한다.
4. 고친 뒤 새 version으로 publish한다.
5. registry UI와 verify 결과를 새 version으로 다시 확인한다.

여기서 중요한 건 문제 버전을 고치는 것이 아니라 수정된 설정으로 다음 버전을 만드는 일이다. npm 문서가 말하듯 publish provenance는 publish 시점의 repository와 workflow 정보에 묶인다. 그러므로 경고가 떴던 과거 버전은 회고 자료로 남기고, 복구는 새 버전에서 확인하는 편이 맞다.

recovery checklist

1. package.json repository.url을 확인한다
2. repo visibility와 publish 위치를 확인한다
3. trusted publisher repository와 workflow filename을 확인한다
4. 새 버전을 publish한다
5. 새 버전의 registry UI warning과 verify 결과를 저장한다

이렇게 하면 recovery 설명도 짧아진다. 예를 들어 rename 뒤 repository.url만 바뀌고 workflow filename은 옛 파일명을 가리키는 경우라면 3단계에서 바로 잡히고, visibility가 private로 바뀐 경우라면 2단계에서 이미 멈출 수 있다. linked source recovery를 한 줄로 설명하려 하지 말고 단계별로 자르는 편이 안전하다.

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

첫 화면은 linked source recovery의 출발점이다. trusted publishers 문서는 package.json의 repository.url이 실제 GitHub repository와 정확히 일치해야 한다고 설명한다.

npm trusted publishers 문서는 repository.url exact match를 요구한다.

즉 rename이나 transfer 뒤 경고가 떴다면 가장 먼저 metadata부터 다시 봐야 한다. registry UI 새로고침보다 빠른 확인점이다.

두 번째 자료는 generating provenance statements 문서의 prerequisite다. npm은 provenance publish를 하려면 public repository가 publish 위치와 case-sensitive하게 맞아야 한다고 설명한다.

npm provenance 문서는 public repository match를 case-sensitive 조건으로 설명한다.

따라서 recovery 순서에서도 URL 문자열만 맞춘 뒤 끝내면 안 된다. visibility와 publish 위치와 casing까지 같이 확인해야 같은 경고가 다시 돌아오지 않는다.

세 번째 자료는 workflow drift를 왜 recovery 순서에 넣어야 하는지 보여 준다. trusted publishers 문서는 repository와 workflow filename이 틀려도 저장 시점에 검증하지 않고, publish 때 오류가 드러날 수 있다고 설명한다.

trusted publishers 문서는 repository와 workflow filename 설정 오류가 publish 시점에야 드러날 수 있다고 설명한다.

즉 linked source 경고를 고칠 때도 package metadata만 맞추고 끝내지 말고 trusted publisher의 repo와 workflow filename까지 같이 다시 맞춰야 한다. 아니면 새 버전에서 다른 층의 오류가 이어질 수 있다.

실무에서는 무엇을 먼저 고치고 무엇을 나중에 재배포할지 순서가 중요하다. recovery 표를 고정해 두면 rename 이후 metadata 수정, trusted publisher 확인, 새 버전 publish, registry 재검증을 한 번에 반복할 수 있다.

linked source repository recovery 순서를 정리한 표다.

이미 incident 허브 글이 linked source와 release record와 approval evidence를 나눴다면, 이번 표는 linked source 한 갈래만 복구 절차로 좁힌 후속편이다.

마지막 자료는 recovery 메모 예시다. 경고 버전, repository.url 수정, trusted publisher 확인, 새 버전 publish, 재검증 결과를 같은 메모에 남기면 나중에 어떤 수정이 실제로 경고를 없앴는지 설명할 수 있다.

linked source repository recovery 메모 예시다.

이 구조가 있으면 metadata와 visibility를 먼저 보는 글과 CLI verify와 UI 로그 순서 글을 실제 복구 runbook으로 이어 붙이기 쉽다.

5. 주의사항과 리스크

첫 번째 리스크는 exact match가 풀리지 않았는데 verify만 반복하는 것이다. 두 번째 리스크는 trusted publisher 설정이 저장 시 검증되지 않는다는 사실을 잊고 workflow drift를 놓치는 것이다. 세 번째 리스크는 고친 뒤에도 같은 version 페이지를 새로고침하며 해결 여부를 판단하는 것이다.

운영 전에 남겨야 할 최소 메모는 warning version, 수정 전후 repository.url, trusted publisher repo, trusted publisher workflow filename, 새 publish version, 재확인 결과다. 이 여섯 줄이 있으면 어떤 수정이 실제로 효과가 있었는지 바로 복기할 수 있다.

• linked source recovery는 UI보다 metadata와 publish config가 먼저다.
• workflow filename drift는 저장 단계가 아니라 publish 단계에서 드러날 수 있다.
• 복구 확인은 새 버전 기준으로 남겨야 한다.

6. 결론

linked source repository 경고를 고칠 때는 registry 페이지를 오래 바라보는 것보다 recovery 순서를 짧게 고정하는 편이 빠르다. repository.url, repo visibility와 publish 위치, trusted publisher의 repository와 workflow filename을 순서대로 다시 맞춘 뒤 새 버전으로 재배포하면 같은 경고를 훨씬 덜 반복하게 된다.

• metadata를 먼저 고치고 trusted publisher를 그다음에 본다.
• 복구 확인은 새 version publish 뒤에 한다.
• 다음 단계는 incident 허브 글과 CLI verify vs UI 로그 글을 이어서 보면 된다.

7. 참고 링크

1. https://docs.npmjs.com/trusted-publishers/
2. https://docs.npmjs.com/generating-provenance-statements/
3. https://docs.npmjs.com/viewing-package-provenance/
4. https://docs.npmjs.com/cli/v11/configuring-npm/package-json/