[npm][보안] trusted publishing을 self-hosted runner에 붙이려 할 때 cloud-hosted 분리와 provenance 기대치를 어떤 순서로 다시 보나

IT 리서치 노트

[npm][보안] trusted publishing을 self-hosted runner에 붙이려 할 때 cloud-hosted 분리와 provenance 기대치를 어떤 순서로 다시 보나

npm trusted publishing으로 토큰 없는 배포를 정리해 두었는데도 실제 릴리스 파이프라인이 self-hosted runner에서 막히면 많은 팀이 workflow 권한이나 repository 연결만 다시 본다. 하지만 2026년 7월 30일 기준 npm 공식 문서를 다시 보면 trusted publishing 지원 runner 범위와 provenance 자동 생성 조건이 먼저 갈린다. 이 글은 self-hosted runner를 쓰는 팀이 cloud-hosted publish 분리와 provenance 기대치를 어떤 순서로 다시 봐야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 self-hosted runner에 붙은 publish job은 trusted publishing 지원 범위부터 다시 봐야 한다. npm 문서는 현재 trusted publishing을 GitHub-hosted, GitLab shared runners, CircleCI cloud에 한정하고 self-hosted는 미래 지원 대상으로 적고 있다. 따라서 OIDC가 안 붙을 때는 권한 YAML보다 release 경로 분리 여부가 더 큰 원인일 수 있다.

또 trusted publishing이면 provenance attestation이 자동 생성되므로, self-hosted token publish에 --provenance만 추가하면 같은 운영 결과가 나오리라고 기대하면 안 된다. 인증 경로와 provenance 생성 경로를 같이 봐야 한다.

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

실무에서 자주 꼬이는 지점은 세 가지다. 첫째, self-hosted runner에서 publish를 계속 재시도하면서 OIDC 권한이나 환경변수만 의심한다. 둘째, publish는 성공했는데 provenance UI가 다르게 보여 trusted publishing까지 성공한 것으로 오해한다. 셋째, build는 내부망이 필요하다는 이유로 publish까지 같은 러너에 묶어야 한다고 가정한다.

npm 문서는 trusted publishing이 OIDC 환경을 자동 감지하고, 지원되지 않으면 기존 인증 방식으로 돌아갈 수 있다고 설명한다. 이 fallback 때문에 더 헷갈리기 쉽다. publish가 되었더라도 그것이 곧 trusted publishing 성공을 뜻하지는 않는다.

즉 self-hosted 환경에서는 질문을 두 갈래로 나눠야 한다. 지금 필요한 것이 '패키지를 어떻게든 올리는 것'인지, 아니면 '토큰 제거와 provenance 자동 생성까지 포함한 경로'인지다. 후자라면 build와 publish를 러너 기준으로 분리하는 설계가 더 현실적일 수 있다.

• 증상: publish는 되는데 trusted publishing으로 보이지 않는다.
• 실패: self-hosted runner에서 OIDC가 붙지 않는 원인을 YAML 오타로만 본다.
• 막힘: --provenance만 추가하면 같은 결과가 나온다고 가정한다.
• 누락: build와 publish를 다른 runner로 쪼개는 선택지를 검토하지 않는다.

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

실무에서는 네 단계가 가장 짧다. 먼저 publish job runner가 npm 문서의 지원 범위에 들어가는지 확인한다. 다음으로 publish가 token fallback인지 OIDC인지 구분한다. 세 번째로 provenance 자동 생성 기대치를 trusted publishing 경로 기준으로 다시 맞춘다. 마지막으로 self-hosted가 꼭 필요한 구간은 build와 test로 한정하고, publish job만 cloud-hosted로 분리한다.

1. runner 지원 범위를 먼저 확인한다.
2. 현재 publish가 OIDC인지 token fallback인지 구분한다.
3. provenance 자동 생성 기대치를 경로별로 분리한다.
4. 필요하면 self-hosted build와 hosted publish로 workflow를 나눈다.

GitHub Actions 화면에서는 publish job의 runner와 권한 필드, npm 설정 파일, provenance 결과 화면을 같은 표로 묶어 확인하는 편이 좋다. 콘솔 로그에서 어떤 명령이 실행됐는지, 어떤 응답이 왔는지, 어떤 파일이 artifact로 넘어갔는지, 어떤 경로에서 publish가 끝났는지를 한 번에 기록해 두면 재발이 줄어든다.

점검 로그 예시

runner=ubuntu-latest
oidc_detected=true
token_fallback=false
publish_command=npm publish
artifact_file=package.tgz
provenance_expected=auto
checked_screen=package-page and provenance-detail

이 순서대로 보면 '왜 안 되지'를 runner 지원 문제와 package page 확인 문제로 분리할 수 있다. publish 보안은 설정 줄 수보다 인증 경로가 무엇이었는지를 분명히 남기는 쪽이 중요하다.

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

첫 자료는 npm trusted publishers 문서의 제한 구간이다. 여기서 먼저 봐야 할 핵심은 self-hosted runner 자체가 아직 지원 대상이 아니라는 점이다.

npm 문서는 trusted publishing이 현재 self-hosted runner를 지원하지 않는다고 설명한다.

즉 publish job이 self-hosted에 붙어 있다면 설정 오타를 계속 고치는 쪽보다, release 경로를 cloud-hosted job으로 분리할지부터 결정하는 편이 빠르다.

두 번째 자료는 npm의 CI/CD 권장 문서다. 지원되는 trusted publishing 경로가 GitHub-hosted, GitLab shared runners로 제한된다는 점을 다시 확인할 수 있다.

npm은 CI/CD publish에서 trusted publishing을 권장하지만 지원 runner 범위는 문서에 적힌 hosted 환경으로 한정한다.

그래서 private registry mirror나 사내 네트워크 빌드가 필요해 self-hosted를 쓰더라도 publish 단계 전체를 같은 러너에 묶어야 한다고 가정하면 설계가 꼬이기 쉽다.

세 번째 자료는 provenance 문서다. trusted publishing이면 provenance attestation이 자동 생성되고 --provenance 플래그가 필수는 아니라고 적혀 있다.

npm 문서는 trusted publishing 경로에서 provenance가 자동 생성된다고 설명한다.

즉 self-hosted에서 token publish를 계속 쓰면서 --provenance만 추가하면 trusted publishing과 같은 결과가 나올 것이라고 기대하면 안 된다. 인증 경로와 provenance 생성 경로를 함께 봐야 한다.

네 번째 자료는 self-hosted와 cloud-hosted를 실제 release 관점으로 나눈 표다. 빌드, 테스트, publish를 같은 러너에 둘 필요가 있는지 여기서 먼저 가를 수 있다.

self-hosted 유지와 cloud-hosted publish 분리를 판단하는 비교표다.

이미 trusted publishing 절차 글을 읽었다면, 이번 표는 '왜 내 self-hosted release가 OIDC로 안 붙는가'라는 다음 질문에 답하는 후속 정리다.

다섯 번째 자료는 practical workflow 예시다. build와 test는 self-hosted에서 돌리고, publish만 GitHub-hosted job으로 분리하는 패턴이 어떤 모양인지 한 번에 보여 준다.

self-hosted build와 GitHub-hosted publish를 분리한 GitHub Actions 예시다.

핵심은 publish job이 별도 artifact를 받아 hosted runner에서 실행된다는 점이다. 이렇게 해야 OIDC 지원 경로와 기존 self-hosted build 요구를 동시에 만족시키기 쉽다.

마지막 자료는 triage 체크리스트다. 지금 막히는 원인이 runner 지원 범위인지, token fallback인지, provenance 기대치 오해인지 순서를 고정해 두면 재시도가 짧아진다.

self-hosted trusted publishing 시도에서 먼저 확인할 triage 순서다.

또 provenance detail 시차 글과 첫 scoped package public 전환 글을 같이 보면 publish 성공 이후 UI 확인 단계까지 연결된다.

self-hosted build와 cloud-hosted publish를 실제로 나눴다면, 다음 단계는 증거를 어떻게 남길지다. 새 후속 글인 artifact handoff 뒤 hosted publish evidence와 release record 필드 순서를 정리한 글을 같이 보면 runner 분리 판단이 운영 메모까지 이어진다.

5. 주의사항과 리스크

첫 번째 리스크는 self-hosted runner publish가 성공했다는 이유만으로 trusted publishing 성공으로 기록하는 것이다. 두 번째 리스크는 내부망 build 요구를 이유로 publish 단계까지 토큰 기반으로 고정하는 것이다. 세 번째 리스크는 provenance UI만 보고 인증 경로를 거꾸로 추정하는 것이다.

운영 문서에는 최소한 release runner 종류, publish 인증 방식, provenance 확인 위치를 같이 남겨 두는 편이 좋다. 그래야 같은 릴리스 체인이 다음 분기에도 다시 설명된다.

• publish 성공과 trusted publishing 성공은 같은 사건이 아닐 수 있다.
• self-hosted 필요 구간과 hosted publish 구간을 분리해 본다.
• provenance는 인증 경로와 함께 읽는다.

6. 결론

self-hosted runner에서 npm trusted publishing이 막힐 때는 runner 지원 범위와 token fallback 여부를 먼저 나누는 편이 가장 빠르다. build와 publish를 다른 runner로 쪼개면 내부망 요구와 OIDC 기반 publish를 함께 만족시키기 쉽고, provenance 기대치도 더 명확해진다.

• publish job runner가 지원 범위인지 먼저 확인한다.
• OIDC와 token fallback을 구분해 기록한다.
• 필요하면 build는 self-hosted, publish는 hosted로 분리한다.

7. 참고 링크

1. https://docs.npmjs.com/trusted-publishers/
2. https://docs.npmjs.com/generating-provenance-statements/
3. https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow/