[npm][보안] self-hosted build artifact handoff 뒤 hosted publish evidence와 release record를 어떤 필드 순서로 같이 남기나

IT 리서치 노트

[npm][보안] self-hosted build artifact handoff 뒤 hosted publish evidence와 release record를 어떤 필드 순서로 같이 남기나

self-hosted runner에서 build를 끝내고 hosted runner에서 npm publish를 하도록 분리하면 OIDC 경로는 맞출 수 있다. 하지만 2026년 8월 6일 기준 npm과 GitHub 공식 문서를 다시 보면, 그 다음 운영 문제는 artifact handoff와 publish evidence를 어떤 기록으로 이어 붙일지다. 이 글은 self-hosted build artifact handoff 뒤 hosted publish evidence와 release record를 어떤 필드 순서로 같이 남기는 편이 실무적으로 좋은지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 self-hosted build를 hosted publish로 넘겼다면 release record 첫 줄은 artifact evidence여야 하고, 둘째 줄은 hosted publish evidence여야 한다. build_run_id, artifact_name, artifact hash를 먼저 고정하고, 그다음 publish job runner, provenance detail, CLI verify 결과를 붙이면 self-hosted와 hosted 경계가 분명해진다.

즉 핵심은 workflow를 분리했다는 사실보다, 분리된 두 job 사이에 어떤 파일이 넘어왔고 어디서 OIDC publish가 끝났는지를 한 메모에 붙이는 일이다.

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

실무에서 흔한 실패는 세 가지다. 첫째, hosted publish job 로그만 남기고 어떤 artifact가 넘어왔는지 안 남긴다. 둘째, artifact는 적지만 publish runner가 hosted 지원 경로였는지 안 남긴다. 셋째, provenance detail URL은 저장해도 build artifact hash나 CLI verify 결과를 함께 저장하지 않는다.

npm 문서는 trusted publishing이 hosted runner에서만 성립한다고 설명하고, GitHub는 artifact가 job 사이에서 파일을 전달한다고 설명한다. 이 둘을 합치면 self-hosted build와 hosted publish 사이 경계는 release record에 artifact evidence로 남아야 한다는 결론이 나온다.

그래서 질문은 두 층으로 나뉜다. 먼저 'publish가 어디서 끝났는가', 그다음 '그 publish가 어떤 self-hosted build 산출물을 사용했는가'다. provenance UI와 OIDC 여부만 보고 끝내면 artifact handoff 경계가 비어 나중에 재현이 느려진다.

• 증상: hosted publish는 성공했는데 어떤 build 산출물을 올렸는지 설명이 안 된다.
• 실패: OIDC publish 증거만 남기고 artifact handoff 증거를 안 남긴다.
• 막힘: provenance detail URL과 release record 필드를 같은 층으로 보지 않는다.
• 누락: artifact hash나 run id가 없어 재현 run을 다시 찾느라 시간이 든다.

질문	먼저 볼 칸	실무 판단
어떤 build 결과를 올렸나	artifact name / hash / build run id	self-hosted build와 publish 경계를 먼저 고정한다
trusted publishing 경로였나	publish job runner / OIDC proof	hosted runner와 token fallback 여부를 남긴다
최종 registry 증거가 맞나	provenance detail / audit signatures	UI와 CLI verify를 함께 저장한다

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

운영 순서는 다섯 단계가 가장 짧다. 먼저 self-hosted build run id와 artifact name을 적는다. 다음으로 artifact hash를 계산해 hosted publish 전후 같은 값인지 확인한다. 세 번째로 publish job runner와 권한 구성을 적는다. 네 번째로 npm provenance detail URL과 npm audit signatures 결과를 붙인다. 마지막으로 이 다섯 칸을 release record 한 장에 남긴다.

1. build run id와 artifact 이름을 먼저 남긴다.
2. artifact hash로 handoff 동일성을 확인한다.
3. publish job runner와 권한을 적는다.
4. provenance detail과 audit signatures 결과를 붙인다.
5. release record를 self-hosted build와 hosted publish 한 장으로 묶는다.

이 구조가 좋은 이유는 hosted publish 증거와 artifact 경계를 अलग각 로그로 남기지 않아도 되기 때문이다. run id, artifact 이름, hash, publish runner, provenance detail, verify 결과를 한 줄로 붙이면 같은 release를 다음 배포와 바로 비교할 수 있다.

release record 예시

build_run_id=1234567890
artifact_name=package-tgz-linux-x64
artifact_sha256=sha256:abcd...
publish_job_runner=ubuntu-latest
oidc_publish=true
provenance_detail_url=https://www.npmjs.com/package/example/v/1.2.3
cli_verify_result=verified

이 순서를 고정해 두면 나중에 provenance detail은 맞는데 artifact handoff 기록이 빠진 경우, 반대로 artifact는 맞는데 publish runner가 token fallback이었던 경우를 빠르게 자를 수 있다.

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

첫 자료는 npm trusted publishers 문서의 제한 구간이다. self-hosted build와 hosted publish를 나누는 이유는 결국 publish 증거가 hosted runner에서만 완성되기 때문이다.

npm 문서는 trusted publishing이 현재 cloud-hosted runner만 지원한다고 설명한다.

따라서 self-hosted build artifact를 넘겼다면 다음 질문은 '어떤 파일을 전달했는가'가 아니라 'hosted publish 증거를 어떤 필드로 남겼는가'가 된다.

두 번째 공식 화면은 GitHub의 artifact handoff 문서다. GitHub는 workflow 안에서 job 간 데이터를 넘길 때 upload-artifact와 download-artifact를 쓰라고 설명한다.

GitHub Actions 문서는 upload-artifact와 download-artifact로 job 간 파일을 전달할 수 있다고 설명한다.

이 구간이 중요한 이유는 publish job이 받은 산출물이 무엇인지 공식적으로 이름 붙일 수 있기 때문이다. artifact name, run id, job id를 release record에 넣으면 self-hosted와 hosted 경계가 분명해진다.

세 번째 자료는 workflow artifacts 개념 문서다. artifact는 job 종료 뒤에도 남아 있고 같은 workflow 다른 job으로 공유할 수 있다고 적혀 있다.

GitHub는 artifact가 job 종료 후에도 남고 다른 job과 공유된다고 설명한다.

즉 hosted publish evidence는 단순 publish command 한 줄이 아니다. 어떤 artifact가 어느 run에서 어느 publish job으로 넘어왔는지를 release record에 함께 남겨야 재현성이 생긴다.

네 번째 공식 화면은 npm provenance 문서다. trusted publishing이면 provenance attestations가 자동 생성된다고 설명한다.

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

그래서 self-hosted build artifact handoff 뒤에는 hosted publish 증거와 provenance detail을 같은 기록으로 붙여야 한다. artifact 경로만 있고 publish proof가 없으면 자동 provenance 설명이 끊긴다.

다섯 번째 자료는 release record 필드표다. 기존 self-hosted runner 글이 runner 분리 자체를 다뤘다면, 이번 표는 그 분리 뒤 어떤 증거를 남겨야 운영 메모가 끊기지 않는지에 초점을 둔다.

self-hosted build artifact handoff 뒤 hosted publish evidence를 남길 release record 필드표다.

이미 self-hosted runner 분리 글을 읽었다면, 이번 표는 hosted publish를 실제 증거 문서로 남기는 다음 단계다. 또 release record 템플릿 글과 바로 이어진다.

마지막 자료는 workflow와 메모 예시다. self-hosted build 결과를 hosted publish job으로 넘길 때 필요한 최소 구조와, 그 뒤 메모에 어떤 칸을 채우면 되는지 같이 적었다.

self-hosted build artifact handoff와 hosted publish 증거 메모를 묶은 예시다.

핵심은 publish proof를 hosted runner 기준으로 따로 남기는 일이다. audit signatures 확인 순서 글과 UI 경고 시차 글을 같이 보면 hosted publish 이후 확인 단계까지 연결된다.

5. 주의사항과 리스크

첫 번째 리스크는 self-hosted build artifact 이름만 남기고 hash를 안 남기는 것이다. 두 번째 리스크는 hosted publish proof가 있는데 어떤 build run에서 왔는지 안 적는 것이다. 세 번째 리스크는 provenance detail URL만 믿고 CLI verify나 release record 필드를 생략하는 것이다.

운영 전에는 최소한 build_run_id, artifact_name, artifact_sha256, publish_job_runner, provenance_detail_url, cli_verify_result 여섯 칸을 같은 release record에 두는 편이 좋다. 이 칸들이 있어야 self-hosted와 hosted 경계가 문서로 남는다.

• artifact evidence와 hosted publish evidence를 अलग 로그로 흩뿌리지 않는다.
• UI proof와 CLI verify를 같이 남긴다.
• release record를 다음 배포와 비교 가능한 형식으로 유지한다.

6. 결론

self-hosted build와 hosted publish를 분리했다면 release record도 두 경계를 이어 붙여야 한다. artifact run id와 hash를 먼저 적고, 그다음 hosted publish runner와 provenance verify를 붙이면 trusted publishing 증거가 운영 메모 안에서 끊기지 않는다.

• artifact evidence를 첫 칸에 둔다.
• hosted publish proof와 provenance verify를 바로 이어 붙인다.
• 같은 형식의 release record를 다음 릴리스에도 반복한다.

7. 참고 링크

1. https://docs.npmjs.com/trusted-publishers/
2. https://docs.npmjs.com/generating-provenance-statements/
3. https://docs.github.com/en/actions/tutorials/store-and-share-data
4. https://docs.github.com/en/actions/concepts/workflows-and-actions/workflow-artifacts