Node.js 패키지 게시하기

이 튜토리얼에서는 지속적 통합(CI) 워크플로우의 일부로 Node.js 패키지를 레지스트리에 게시하는 방법을 알려드릴게요.

출처: 문서

본문

Introduction

이 가이드는 CI 테스트가 통과한 후 Node.js 패키지를 GitHub Packages 및 npm 레지스트리에 게시하는 워크플로우를 만드는 방법을 보여줍니다.

Prerequisites

워크플로우 구성 옵션과 워크플로우 파일을 만드는 방법에 대한 기본적인 이해가 있으면 좋아요. 자세한 내용은 Writing workflows 문서를 참고하세요.

Node.js 프로젝트를 위한 CI 워크플로우를 만드는 방법에 대한 자세한 내용은 Building and testing Node.js 문서를 참고하세요.

다음에 대한 기본적인 이해가 있으면 더 도움이 될 수 있어요.

About package configuration

package.json 파일의 name 및 version 필드는 레지스트리가 패키지를 레지스트리에 연결하는 데 사용하는 고유 식별자를 만들어요. package.json 파일에 description 필드를 포함해서 패키지 목록 페이지에 요약을 추가할 수 있어요. 자세한 내용은 npm 문서의 Creating a package.json file 및 Creating Node.js modules을 참고하세요.

로컬 .npmrc 파일이 있고 registry 값이 지정되어 있다면 npm publish 명령은 .npmrc 파일에 구성된 레지스트리를 사용해요. setup-node 액션을 사용해서 기본 레지스트리와 스코프를 구성하는 로컬 .npmrc 파일을 러너에 만들 수 있어요. setup-node 액션은 비공개 레지스트리에 접근하거나 노드 패키지를 게시하는 데 사용되는 인증 토큰을 입력으로 받기도 해요. 자세한 내용은 setup-node을 참고하세요.

setup-node 액션을 사용해서 러너에 설치된 Node.js 버전을 지정할 수 있어요.

워크플로우에 package.json 파일의 publishConfig 필드를 구성하는 단계를 추가한다면 setup-node 액션으로 registry-url을 지정할 필요가 없지만, 패키지를 하나의 레지스트리에만 게시할 수 있게 돼요. 자세한 내용은 npm 문서의 publishConfig를 참고하세요.

Publishing packages to the npm registry

새 릴리스를 게시할 때마다 패키지를 게시하도록 워크플로우를 트리거할 수 있어요. 다음 예시의 프로세스는 published 유형의 release 이벤트가 트리거될 때 실행돼요. CI 테스트가 통과하면 프로세스가 패키지를 npm 레지스트리에 업로드해요. 자세한 내용은 Managing releases in a repository 문서를 참고하세요.

워크플로우에서 npm 레지스트리에 대해 인증된 작업을 수행하려면 npm 인증 토큰을 secret으로 저장해야 해요. 예를 들어 NPM_TOKEN이라는 저장소 secret을 만드세요. 자세한 내용은 Using secrets in GitHub Actions 문서를 참고하세요.

기본적으로 npm은 package.json 파일의 name 필드를 사용해서 게시된 패키지의 이름을 결정해요. 전역 네임스페이스에 게시할 때는 패키지 이름만 포함하면 돼요. 예를 들어 my-package라는 패키지를 https://www.npmjs.com/package/my-package에 게시할 거예요.

스코프 접두사를 포함하는 패키지를 게시한다면 package.json 파일의 이름에 스코프를 포함하세요. 예를 들어 npm 스코프 접두사가 "octocat"이고 패키지 이름이 "hello-world"라면 package.json 파일의 name은 @octocat/hello-world여야 해요. npm 패키지가 스코프 접두사를 사용하고 공개라면 npm publish --access public 옵션을 사용해야 해요. 이는 npm이 누군가 실수로 비공개 패키지를 게시하는 것을 방지하기 위해 요구하는 옵션이에요.

패키지를 증언(provenance)과 함께 게시하려면 npm publish 명령에 --provenance 플래그를 포함하세요. 이렇게 하면 패키지가 어디서 어떻게 빌드되었는지 공개적이고 검증 가능하게 확립할 수 있어서, 패키지를 소비하는 사람들의 공급망 보안이 강화돼요. 자세한 내용은 npm 문서의 Generating provenance statements를 참고하세요.

이 예시는 NPM_TOKEN secret을 NODE_AUTH_TOKEN 환경 변수에 저장해요. setup-node 액션이 .npmrc 파일을 만들 때 NODE_AUTH_TOKEN 환경 변수에서 토큰을 참조해요.

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v7
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

위 예시에서 setup-node 액션은 다음 내용으로 러너에 .npmrc 파일을 만들어요.

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
registry=https://registry.npmjs.org/
always-auth=true

자격 증명을 올바르게 구성하려면 setup-node에서 registry-url을 https://registry.npmjs.org/로 설정해야 한다는 점에 유의하세요.

Publishing packages to GitHub Packages

새 릴리스를 게시할 때마다 패키지를 게시하도록 워크플로우를 트리거할 수 있어요. 다음 예시의 프로세스는 published 유형의 release 이벤트가 트리거될 때 실행돼요. CI 테스트가 통과하면 프로세스가 패키지를 GitHub Packages에 업로드해요. 자세한 내용은 Managing releases in a repository 문서를 참고하세요.

Configuring the destination repository

repository 키를 사용해서 패키지를 GitHub Packages에 연결하는 것은 선택사항이에요. package.json 파일에 repository 키를 제공하지 않기로 선택하면 패키지가 게시될 때 저장소에 연결되지 않지만, 나중에 패키지를 저장소에 연결하도록 선택할 수 있어요.

package.json 파일에 repository 키를 제공한다면 해당 키의 저장소가 GitHub Packages의 대상 npm 레지스트리로 사용돼요. 예를 들어 아래 package.json을 게시하면 my-package라는 패키지가 octocat/my-other-repo GitHub 저장소에 게시돼요.

{
  "name": "@octocat/my-package",
  "repository": {
    "type": "git",
    "url": "https://github.com/octocat/my-other-repo.git"
  }
}

Authenticating to the destination repository

워크플로우에서 GitHub Packages 레지스트리에 대해 인증된 작업을 수행하려면 GITHUB_TOKEN을 사용할 수 있어요. GITHUB_TOKEN secret은 워크플로우의 각 job이 시작될 때마다 저장소에 대한 액세스 토큰으로 설정돼요. contents 권한에 대한 읽기 액세스와 packages 권한에 대한 쓰기 액세스를 부여하도록 워크플로우 파일에서 이 액세스 토큰의 권한을 설정해야 해요. 자세한 내용은 Use GITHUB_TOKEN for authentication in workflows 문서를 참고하세요.

패키지를 다른 저장소에 게시하려면 대상 저장소의 패키지에 쓸 수 있는 권한이 있는 personal access token(classic)을 사용해야 해요. 자세한 내용은 Managing your personal access tokens 및 Using secrets in GitHub Actions 문서를 참고하세요.

Example workflow

이 예시는 GITHUB_TOKEN secret을 NODE_AUTH_TOKEN 환경 변수에 저장해요. setup-node 액션이 .npmrc 파일을 만들 때 NODE_AUTH_TOKEN 환경 변수에서 토큰을 참조해요.

name: Publish package to GitHub Packages
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v6
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v7
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

setup-node 액션은 러너에 .npmrc 파일을 만들어요. setup-node 액션에 scope 입력을 사용하면 .npmrc 파일에 스코프 접두사가 포함돼요. 기본적으로 setup-node 액션은 .npmrc 파일의 스코프를 워크플로우 파일을 소유한 계정으로 설정해요.

//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://npm.pkg.github.com
always-auth=true

Publishing packages using Yarn

Yarn 패키지 관리자를 사용한다면 Yarn으로 패키지를 설치하고 게시할 수 있어요.

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v7
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

게시 중에 레지스트리로 인증하려면 인증 토큰이 yarnrc.yml 파일에도 정의되어 있는지 확인하세요. 자세한 내용은 Yarn 문서의 Settings 문서를 참고하세요.

Node.js 패키지 게시하기