릴리스 워크플로를 나누고 나면 npm 배포에서 꼭 한 번 막힌다. 정식 태그는 publish.yml, prerelease는 next.yml, 검증용은 별도 workflow인데 trusted publisher 설정은 하나뿐인 경우다. 결국 한쪽에는 예외를 만들거나, 더 불편하게는 토큰을 다시 넣게 된다.
GitHub는 2026년 9월 3일 npm 패키지마다 여러 trusted publishing(OIDC) 설정을 둘 수 있다고 발표했다. 각 설정은 저장소, workflow, environment 조건을 따로 가지며, 들어온 OIDC 토큰이 설정 중 하나와 맞으면 배포 또는 stage가 허용된다. 설정끼리 순서나 우선순위를 기대하면 안 된다. GitHub 변경 공지에 나온 내용이다.
이 기능의 실무적인 용도는 단순하다. 릴리스 경로를 억지로 한 workflow에 합치지 말고, 각 경로에 필요한 권한만 주는 것이다.
먼저 확인할 것
npm 문서 기준으로 trusted publishing은 CI/CD가 발급한 짧은 OIDC 토큰으로 npm에 배포하는 방식이다. 장기 쓰기 토큰을 secret에 넣지 않아도 된다. GitHub Actions를 쓴다면 해당 job에는 id-token: write가 필요하다. 지원 조건과 전체 설정 화면은 npm trusted publishers 문서에서 확인할 수 있다.
필요한 workflow 권한
- contents: read
- id-token: write
패키지 설정에서 trusted publisher를 추가할 때는 저장소 이름과 workflow 파일명을 정확히 입력한다. release.yml만 허용할 생각이면 ci.yml이나 재사용 workflow까지 넓게 잡지 않는 편이 낫다. npm은 설정을 저장하는 시점에 이 조합을 검증하지 않으므로, 오타는 실제 배포 때 발견된다.
설정을 늘렸다면 기본값은 stage로 두는 편이 낫다
이번 변경에서 새 설정은 기본적으로 stage할 수 있고, registry에 바로 올리는 npm publish는 설정별 opt-in이다. 예를 들어 정식 릴리스 workflow만 직접 배포를 허용하고, prerelease와 수동 검증 workflow는 stage만 허용하는 식으로 둘 수 있다.
릴리스 workflow의 순서
- id-token: write 권한을 준다.
- 의존성을 설치하고 테스트한다.
- npm stage publish로 검토 대기 상태에 올린다.
npm stage publish는 바로 공개하지 않는다. maintainer가 CLI 또는 npmjs.com에서 검토하고 2FA로 승인해야 registry에 나온다. npm의 staged publishing 문서도 이 승인 단계를 명시한다. 배포 workflow가 탈취되더라도 자동으로 공개 버전을 밀어 넣는 경로 하나를 없애는 셈이다.
이번 릴리스에서는 staged 패키지의 승인 버튼도 malware scan이 끝날 때까지 비활성화된다. scan 결과를 해석하는 별도 절차가 필요한지는 패키지 성격과 팀의 운영 정책에 따라 다르므로 출처 확인 필요. 다만 공개 전 멈출 수 있는 지점이 생긴 것은 분명하다.
토큰을 바로 지우기 전에 한 번 배포해 본다
기존 NPM_TOKEN을 즉시 삭제하면 private dependency 설치까지 끊길 수 있다. trusted publishing은 publish 또는 stage 작업을 위한 인증이고, private package를 설치하는 읽기 권한까지 대신하지는 않는다. npm도 먼저 trusted publisher를 설정해 실제 배포를 확인한 뒤 기존 automation token을 폐기하는 순서를 권장한다.
내가 정리할 때는 아래 세 가지만 확인하면 될 것 같다.
- 패키지 설정에 정식 배포, prerelease, 검증 workflow가 각각 필요한 만큼만 등록됐는가
- 자동 경로는 npm stage publish만 허용하고, 직접 배포가 꼭 필요한 workflow만 npm publish를 허용했는가
- 쓰기 토큰을 없앤 뒤에도 private dependency 설치에 필요한 읽기 토큰은 최소 권한으로 남아 있는가
설정 수가 늘었다고 권한을 넓히는 기능은 아니다. 오히려 workflow별로 배포 권한을 잘라낼 수 있게 된 변경이다.
참고: GitHub 변경 공지, npm trusted publishers, npm staged publishing