npm 배포 경로가 10개로 늘었다…OIDC 권한은 합집합으로 열린다

npm 패키지는 이제 OIDC 신뢰 게시자를 기존 1개가 아닌 최대 10개까지 등록할 수 있다. 안정판·프리릴리스·스테이징처럼 배포 목적별 워크플로를 분리하려면 각 경로를 별도 Trusted Publisher 구성으로 추가하고, 저장소·워크플로 파일·환경·허용 작업을 실제 CI 설정과 정확히 맞추면 된다.

주의할 점은 여러 구성이 서로를 제한하지 않는다는 것이다. 들어온 OIDC 토큰이 등록된 구성 가운데 하나만 충족해도 게시 또는 스테이징이 승인된다. 따라서 운영 관점의 권한 범위는 교집합이 아니라 합집합이며, 가장 엄격한 안정판 구성만 확인해서는 전체 게시 권한을 판단할 수 없다.

1. 배포 목적과 승인 수준부터 분리한다

GitHub의 npm 변경 공지 에 따르면 각 구성은 자체 저장소·워크플로·환경 조건을 가진 독립적인 승인 경로이며, 어느 하나가 일치하면 승인되고 평가 순서도 보장되지 않는다. 이전에는 패키지당 구성 하나만 둘 수 있었지만, 다중 구성이 정식 제공되면서 안정판·프리릴리스·스테이징을 별도 경로로 만들 수 있게 됐다.

먼저 현재 배포 작업을 목적별로 정리한다. 아래 구분은 조건을 설계하기 위한 예시이며, 환경 이름과 워크플로 파일명은 실제 저장소의 값과 일치해야 한다.

• 안정판: 정식 버전을 배포하는 워크플로와 보호된 production 환경을 연결하고, 즉시 공개가 꼭 필요한지 판단한다.
• 프리릴리스: beta나 next 같은 dist-tag를 쓰는 작업을 안정판 워크플로와 분리하고 별도 환경 승인 규칙을 적용한다.
• 스테이징: 자동화가 패키지를 대기열에 올리되 관리자가 검토한 뒤 공개하도록 구성한다.

한 워크플로가 세 역할을 모두 맡고 있다면 npm 연결을 늘리는 것만으로는 권한이 분리되지 않는다. 먼저 CI 파일이나 배포 작업을 목적별로 나눈 뒤 각각을 npm 구성에 연결해야 변경 권한과 환경 보호 규칙을 따로 관리할 수 있다.

2. npm에서 경로별 Trusted Publisher를 등록한다

npm의 Trusted Publishing 공식 문서 는 패키지당 동시 연결 한도를 10개로 정하고 GitHub-hosted Actions, GitLab.com shared runner, CircleCI cloud를 지원한다고 명시한다. 자체 호스팅 러너는 지원하지 않으며, Trusted Publishing에는 npm CLI 11.5.1 이상과 Node.js 22.14.0 이상이 필요하다.

1. npmjs.com에서 패키지의 Settings → Trusted publishing으로 이동해 Add trusted publisher를 선택한다.
2. 실제 배포에 사용하는 CI 공급자를 고른다.
3. GitHub Actions라면 Organization or user, Repository, Workflow filename을 입력한다. 파일명은 전체 경로가 아닌 publish.yml 또는 publish.yaml 형식으로 적는다.
4. 배포 작업이 GitHub Environment를 사용한다면 Environment name도 입력한다. 생략하면 그 환경은 npm의 일치 조건에 포함되지 않는다.
5. Allowed actions에서 스테이징만 허용할지, 직접 npm publish도 허용할지 정한다.
6. 나머지 배포 경로도 별도 항목으로 추가한 뒤 CI의 실제 값과 대조한다.

GitLab CI/CD는 Namespace, Project name, 최상위 CI 파일 경로를 입력하며 환경 이름은 선택 사항이다. CircleCI는 Organization ID, Project ID, Pipeline definition ID, VCS origin이 필수이고 필요한 경우 Context ID로 범위를 더 좁힐 수 있다. 같은 패키지라도 서로 다른 CI 공급자를 함께 등록할 수 있다.

GitHub Actions 워크플로에는 OIDC 토큰 발급을 위한 id-token: write 권한이 필요하다. GitLab은 npm용 ID 토큰의 audience를 npm:registry.npmjs.org로 설정해야 하고, CircleCI는 발급받은 토큰을 NPM_ID_TOKEN 환경 변수로 전달한다. npm은 저장 시 연결 값을 검증하지 않으므로 오타나 대소문자 불일치는 실제 게시 시점에야 오류로 나타날 수 있다.

3. 생성 시점에 따라 Allowed actions를 확인한다

새 구성에서는 npm stage publish가 자동으로 허용되고, 직접 npm publish는 구성별 선택 사항이다. 스테이징 전용으로 두면 CI가 올린 버전은 즉시 공개되지 않으며, 유지 관리자가 CLI 또는 npmjs.com에서 2FA를 거쳐 검토·승인해야 공개된다.

기존 구성은 생성 시점에 따라 초기값이 다르다. 2026년 5월 20일 이전에 만든 구성은 기존 동작을 보존하기 위해 npm publish만 허용된다. 2026년 9월 3일 이전 구성에는 원래 선택된 작업이 그대로 유지되고, 그 이후 생성한 구성은 npm stage publish가 자동 허용되며 직접 게시는 별도로 선택한다.

따라서 워크플로 이름에 staging이나 prerelease가 들어 있다는 이유만으로 권한을 추정하면 안 된다. 목록의 각 항목을 열어 실제 Allowed actions를 확인하고, 직접 게시가 불필요한 구성에서는 npm publish 허용을 제거해야 한다.

4. 권한 합집합을 항목별로 감사한다

다중 구성에서는 오래된 시험용 경로 하나도 독립적인 게시 입구다. production 환경을 사용하는 안정판 구성이 엄격하더라도, 환경 조건이 빠진 다른 구성이 같은 패키지의 게시를 승인할 수 있다. 감사 기준은 가장 강한 경로가 아니라 가장 느슨한 유효 경로여야 한다.

GitHub의 OIDC 참조 문서 는 저장소를 나타내는 repo, 환경을 포함할 수 있는 context, 재사용 워크플로를 식별하는 job_workflow_ref 같은 값을 신뢰 조건에 활용하는 방식을 설명한다. npm에 등록한 문자열뿐 아니라 해당 저장소의 워크플로 변경 권한과 Environment 보호 규칙까지 함께 살펴야 하는 이유다.

• 각 연결이 현재 관리 중인 정확한 조직·저장소·프로젝트를 가리키는가
• 워크플로 파일명이 확장자와 대소문자를 포함해 실제 파일과 일치하는가
• 환경 승인이 필요한 경로에 Environment name이 빠지지 않았는가
• production과 prerelease 환경의 승인자와 배포 제한이 목적에 맞는가
• 직접 npm publish가 필요한 연결에서만 해당 작업이 허용됐는가
• 폐기한 저장소, 이름을 바꾼 워크플로, 임시 시험 연결이 남아 있지 않은가
• 신뢰된 워크플로를 수정할 수 있는 사람과 브랜치 보호 규칙이 적절한가

기존 연결의 공급자와 필수 필드는 생성 후 수정할 수 없다. 값을 바꾸려면 새 연결을 만들고 게시 경로가 정상적으로 작동하는지 확인한 뒤 이전 연결을 삭제해야 한다. 교체 중에는 두 구성이 모두 유효하므로 병행 기간을 짧게 유지하고 이전 항목 삭제를 변경 완료 조건으로 잡는다.

5. 성공 경로와 거부 경로를 함께 검증한다

등록을 마치면 먼저 의도한 조건에서 각 경로를 실행한다. 안정판은 지정한 워크플로와 production 환경에서만 동작하는지, 프리릴리스는 올바른 dist-tag를 쓰는지, 스테이징은 공개되지 않고 승인 대기 상태에 머무는지 확인한다.

이어 통제된 실패 테스트를 수행한다. 등록하지 않은 워크플로 파일, 다른 Environment, 다른 저장소에서 같은 패키지의 게시를 시도했을 때 거부돼야 한다. 저장 단계에서 검증되지 않은 입력 오류와 예상보다 넓은 신뢰 범위를 실제 실행 전에 발견하기 위한 절차다.

Trusted Publishing을 설정해도 기존 npm 토큰이나 수동 게시가 자동으로 차단되지는 않는다. OIDC 전환을 확인한 뒤 패키지의 Publishing access에서 토큰 게시를 금지하고, 더 이상 필요 없는 자동화 토큰을 폐기해야 별도의 우회 경로가 남지 않는다.

운영 목록에는 패키지, 배포 목적, CI 공급자, 저장소, 워크플로 파일, 환경, 허용 작업, 담당 팀을 구성별로 기록한다. 릴리스 파이프라인이나 담당 조직이 바뀔 때 이 목록을 npm 설정과 대조하면, 최대 10개로 늘어난 편의가 방치된 권한으로 변하는 것을 막을 수 있다.

함께 읽기:

• CrowdStrike가 npm·PyPI 다운로드를 가로막는다…악성 코드 실행 전 차단