[npm][보안] Trusted Publishing으로 npm token 없이 배포하는 절차

IT 리서치 노트

[npm][보안] Trusted Publishing으로 npm token 없이 배포하는 절차

npm 패키지 배포에서 장기 토큰을 GitHub Actions secret에 넣는 방식은 아직도 흔하지만, 현재 npm 공식 문서는 Trusted Publishing을 권장한다. 핵심은 OIDC 기반으로 배포 시점에만 짧은 권한을 받는 것이다. 이 글은 어떤 저장소와 workflow를 신뢰 관계에 묶는지, 2FA와 provenance가 어떻게 달라지는지, 기존 token 배포를 바꿀 때 어디서 막히는지를 순서대로 정리한다.

목차

1. 개요
2. 어디서 막히는가
3. 실제로 해결하는 순서
4. 화면과 출력으로 확인하기
5. 주의할 점
6. 결론
7. 참고 링크

1. 개요

npm 패키지 배포에서 장기 토큰을 GitHub Actions secret에 넣는 방식은 아직도 흔하지만, 현재 npm 공식 문서는 Trusted Publishing을 권장한다. 핵심은 OIDC 기반으로 배포 시점에만 짧은 권한을 받는 것이다.

이 글은 어떤 저장소와 workflow를 신뢰 관계에 묶는지, 2FA와 provenance가 어떻게 달라지는지, 기존 token 배포를 바꿀 때 어디서 막히는지를 순서대로 정리한다.

• 이 글은 현재 공식 문서와 공개 도움말을 다시 확인한 뒤 정리했다.
• 설정 경로, 실패 지점, 검증 결과를 분리해서 읽으면 바로 실행에 옮기기 쉽다.
• 실제 운영에서는 권한, 비용, 배포 로그를 함께 봐야 같은 실수를 반복하지 않는다.

2. 어디서 막히는가

문제가 길게 보이더라도 실제 막힘은 몇 가지 패턴으로 모인다. 아래 증상 중 하나라도 보이면 설정값, 요청값, 실행 결과를 분리해서 기록하는 쪽이 빠르다.

• npm access token이 오래 남아 퇴사자나 오래된 workflow에서도 계속 쓸 수 있다.
• GitHub Actions에서 publish는 되지만 provenance가 붙지 않아 공급망 신뢰를 설명하기 어렵다.
• Trusted Publisher를 등록했는데 repository와 workflow 조건이 맞지 않아 배포가 거부된다.
• 2FA와 CI 배포 관계를 잘못 이해해 토큰 bypass 설정만 유지한다.

여기서 가장 흔한 실수는 증상만 보고 권한을 넓히거나 비용 플랜을 올리거나, 별도 로그 없이 다시 시도하는 것이다. 그러면 당장은 지나가도 다음 배포나 다음 운영 시간대에 같은 문제가 다시 나온다.

따라서 먼저 실제 값과 공식 기준이 어떻게 다른지 좁히고, 그 다음에 클릭, 입력, 실행, 저장 순서를 하나씩 재현해야 한다. 이 순서가 있어야 팀원끼리 같은 결과를 볼 수 있다.

문제정의 단계에서는 오류 문구 한 줄만 보는 대신, 어떤 메뉴에서 확인했고 어떤 필드가 비어 있었는지, 어떤 응답 상태가 먼저 나타났는지까지 적어두는 편이 좋다. 그래야 해결 단계에서 값을 바꾼 뒤에도 같은 기준으로 성공과 실패를 다시 비교할 수 있다.

특히 비용 문제나 권한 문제는 겉으로는 비슷하게 보여도 원인이 다르다. 청구 화면, 콘솔 설정, 배포 로그, 브라우저 요청, CLI 출력 가운데 무엇이 기준 화면인지 먼저 정하고 그 화면을 중심으로 확인해야 엉뚱한 메뉴를 오래 헤매지 않는다.

3. 실제로 해결하는 순서

아래 순서는 메뉴를 열고 값을 확인하고 결과를 다시 보는 실무용 순서다. 한 번에 모두 바꾸지 말고 한 단계씩 적용한 뒤 출력과 화면을 확인하는 편이 안전하다.

1. npm 패키지와 GitHub 저장소 연결 범위를 먼저 확인한다.
2. npm Trusted Publisher 설정에서 repository와 workflow를 명시한다.
3. workflow에는 id-token: write를 넣고 장기 npm token은 제거한다. 이 권한이 빠져 OIDC 토큰 요청 단계에서 막히는 경우는 GitHub Actions OIDC의 id-token: write 실패 원인을 먼저 확인한다.
4. 배포 후 provenance와 패키지 publish 기록이 기대대로 남는지 확인한다.

안전한 예제 코드

name: publish-package
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: "https://registry.npmjs.org"
      - run: npm ci
      - run: npm publish --provenance

Trusted Publishing을 쓰면 장기 npm token이 없어도 된다. 다만 실제 패키지 이름과 조직명은 예제에서 감췄다.

예제 코드는 흐름만 남겼다. 실제 토큰, 계정, 내부 서버 주소, 비공개 저장소 이름은 placeholder로 바꾸고 서버 환경변수나 보안 저장소로 분리한다.

중요한 점은 설정 변경 직후 바로 다음 단계로 넘어가지 않는 것이다. 각 단계마다 어떤 메뉴를 클릭했고, 어떤 값을 입력했고, 어떤 출력이 돌아왔는지 짧게라도 기록해야 한다. 그래야 실패했을 때 마지막으로 바뀐 값이 무엇인지 빠르게 되짚을 수 있다.

또한 해결 절차는 한 번 성공했다고 끝나지 않는다. 같은 절차를 다른 환경이나 다른 브랜치, 다른 계정에서도 다시 실행해 보고 결과가 같은지 확인해야 한다. 운영 환경과 로컬 환경의 URL, 권한, 캐시, 플랜, 리전 차이가 숨어 있으면 여기서 드러나는 경우가 많다.

4. npm 문서 화면으로 배포 흐름 확인하기

Trusted Publishing은 npm token을 더 안전하게 보관하는 기술이 아니라, CI에서 장기 토큰을 없애는 방식이다. 아래 화면에서는 신뢰 게시자 등록, CI 설정, provenance 확인을 순서대로 본다.

먼저 trusted publishing 문서의 시작 화면을 확인한다. 이 기능은 패키지 배포를 특정 CI provider와 OIDC 신뢰 관계로 묶는 방식이다.

Trusted publishing 문서에서는 npm token 없이 배포할 수 있는 기본 조건을 확인한다.

모든 CI에서 같은 방식으로 되는 것은 아니다. 지원 provider 목록을 먼저 확인해야 배포 파이프라인을 잘못 설계하지 않는다.

Supported CI/CD providers 화면에서는 현재 사용하는 CI가 trusted publishing 대상인지 확인한다.

npmjs.com 쪽 설정은 배포 실패의 흔한 원인이다. repository, workflow filename, environment 조건이 CI 파일과 정확히 맞아야 한다.

trusted publisher 추가 단계에서는 npm 패키지와 CI workflow를 어떤 값으로 연결하는지 확인한다.

기존 token 기반 CI 문서를 보면 npm이 trusted publishing을 권장하는 맥락을 확인할 수 있다. 남겨야 할 token과 없앨 token을 구분하는 데 도움이 된다.

CI/CD workflow 문서에서는 패키지 게시에 trusted publishing을 우선 검토하라는 기준을 확인한다.

마지막으로 provenance 문서를 함께 본다. 배포가 성공했는지뿐 아니라 어떤 workflow에서 만들어진 패키지인지 추적할 수 있어야 한다.

provenance 화면에서는 GitHub Actions 배포 결과를 증명 가능한 형태로 남기는 설정을 확인한다.

이 순서로 확인하면 문서의 기능 설명, 설정 범위, 제한 조건, 실제 운영 판단 기준을 한 번에 대조할 수 있다. 화면에서 먼저 볼 항목을 정한 뒤 코드나 콘솔 설정을 수정해야 같은 문제가 반복되지 않는다. publish는 성공했는데 provenance가 기대대로 붙지 않는다면 provenance attestation이 안 붙을 때 GitHub Actions에서 먼저 볼 값을 이어서 확인하는 편이 빠르다.

5. 주의할 점

설정을 맞췄더라도 운영에서는 다시 틀어지는 지점이 있다. 아래 항목은 배포 직전과 배포 직후에 꼭 다시 점검할 부분이다.

• repository나 workflow 이름이 설정과 다르면 배포가 바로 실패한다.
• 장기 token을 남겨두면 Trusted Publishing으로 바꿔도 위험이 완전히 줄지 않는다.
• 패키지 publish 권한과 org 정책을 같이 보지 않으면 전환 중 중단이 생길 수 있다.

특히 권한, 비용, 캐시, 재시도 정책은 한 번 맞춘 뒤에도 환경이 바뀌면 다시 확인해야 한다. 문서가 바뀌었는지, 콘솔 기본값이 달라졌는지, 팀의 배포 방식이 바뀌었는지도 같이 본다.

6. 결론

GitHub-hosted runner에서 배포한다면 Trusted Publishing 전환 우선순위가 높다.

• GitHub-hosted runner에서 배포한다면 Trusted Publishing 전환 우선순위가 높다.
• 패키지 신뢰와 토큰 회전 부담을 같이 줄이고 싶다면 바로 전환할 가치가 있다.
• self-hosted runner나 별도 CI라면 지원 범위를 먼저 확인한다.

핵심은 추상적인 '좋은 설정'을 찾는 것이 아니라, 지금 내 서비스에서 어떤 값과 어떤 출력이 정답인지 빠르게 확인하는 것이다. 이 글의 순서대로 문서, 설정, 실행 결과를 묶어 보면 같은 문제를 다시 만났을 때 훨씬 빨리 끝낼 수 있다.

Trusted Publishing 자체는 끝냈지만 provenance 판단 기준이 아직 헷갈린다면 후속 글인 Trusted Publishing을 쓰는데 --provenance를 또 붙여야 하는지와 npm audit signatures 확인 순서 글로 이어 가면 인증 경로와 배포 후 검증 단계를 더 좁게 다시 정리할 수 있다.

다만 실제 릴리스가 self-hosted runner에 남아 있다면 trusted publishing 지원 범위와 provenance 기대치를 다시 갈라 봐야 한다. 그 경우에는 후속 글인 self-hosted runner와 cloud-hosted publish 분리 글로 이어 가면 publish job을 어디서 분리하고 어떤 로그를 확인할지 더 구체적으로 정리할 수 있다.

7. 참고 링크

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