npm latest 태그, 저장 토큰 없이 OIDC로 바꾸는 법

태그 관리 때문에 남겨 둔 토큰을 없앨 수 있다

이미 OIDC로 npm 패키지를 발행하는 CI도 태그 관리 권한은 따로 받아야 한다. 9월 30일 추가된 Allow npm dist-tag를 해당 trusted publisher 설정에서 켜면, 저장해 둔 npm 액세스 토큰 없이 태그 작업을 인증할 수 있다. 새 설정과 기존 설정 모두 기본값은 꺼짐이다.

이전에는 OIDC로 발행을 옮겨도 태그 때문에 토큰을 유지하는 경우가 있었다. GitHub 커뮤니티의 2025년 논의에서도 여러 태그를 관리하기 위한 API 토큰이 필요하다는 요청과 전환 뒤 태그 자동화가 영향을 받았다는 질문이 나왔다. 이번 권한은 그 작업을 OIDC로 처리할 수 있게 한다.

직접 발행 권한과 태그 권한은 독립적이다. 스테이징만 허용한 설정에도 태그 권한을 줄 수 있으며, 기존 토큰 방식도 계속 동작한다. 따라서 발행 설정 전체를 바꾸기보다 태그를 맡길 워크플로의 권한을 선택하면 된다.

publish를 지원하는 npm이면 충분한 것은 아니다

npm 공식 문서는 OIDC 태그 관리에 npm 11.21.0 이상 또는 12 계열의 12.2.0 이상을 요구한다. 일반 trusted publishing의 최소 버전인 11.5.1과 다르다. 확인할 버전은 개발자 PC가 아니라 태그 명령을 실행하는 CI의 버전이다.

npm --version

GitHub Actions에서는 GitHub 호스팅 러너를 기준으로, npm 패키지 설정에 등록한 저장소·워크플로 파일명이 실제 실행과 맞아야 한다. 해당 설정의 Allow npm dist-tag를 켜고 job에는 id-token: write를 허용한다.

OIDC는 실행 중인 job의 신원을 증명한다. GitHub에서 신원 토큰을 받을 수 있다는 사실만으로 npm 패키지를 수정할 권한이 생기는 것은 아니다. npm 쪽의 신뢰 설정과 허용 작업도 함께 맞아야 한다.

이미 공개한 버전에 latest라는 이름을 붙인다

dist-tag는 특정 버전을 가리키는 이름이다. 새 파일을 올리는 작업과 구별되며, 여러 배포 채널을 운영할 때 사용할 수 있다. 아래는 example-package의 2.1.0이 이미 공개돼 있다고 가정한 예제다. 실제 패키지와 의도한 공개 버전으로 바꿔, 권한을 설정한 CI 안에서 실행한다.

npm dist-tag ls example-package
npm dist-tag add [email protected] latest
npm dist-tag ls example-package

npm CLI 명령 설명에 따르면 버전이나 태그를 지정하지 않은 npm install example-package는 기본적으로 latest를 선택한다. 태그가 가리킬 버전을 정확히 지정해야 하는 이유다. 시험 채널만 바꾸려면 위 명령의 latest 대신 프로젝트가 사용하는 next 같은 이름을 쓴다.

npm dist-tag rm example-package beta는 beta 태그를 제거하는 명령이다. 패키지 버전을 삭제하는 명령으로 해석해서는 안 된다. 태그를 옮기는 목적이라면 새 버전을 다시 발행할 필요 없이 add로 대상 버전을 지정한다.

조회 성공만으로 쓰기 권한을 검증할 수 없다

공개 패키지의 태그는 인증 없이도 읽을 수 있다. 따라서 ls 성공은 태그 변경 권한이 있다는 증거가 아니며, npm whoami 역시 trusted publishing 권한 검사 명령이 아니다. npm은 실제로 수행할 작업으로 확인하도록 안내한다.

발행은 되는데 태그 작업만 실패한다면 CI의 npm 버전과 실행 워크플로에 대응하는 권한을 다시 확인한다. 저장 토큰에 의존하던 태그 변경을 OIDC로 수행하고 결과까지 확인한 뒤에야 그 토큰을 정리할 수 있다. 이 성공이 비공개 패키지 설치 등 다른 npm 작업의 인증까지 대신하는 것은 아니다.