Node.js 패키지 게시

이 자습서에서는 CI(연속 통합) 워크플로의 일부로 Node.js 패키지를 레지스트리에 게시하는 방법을 알아봅니다.

이 기사에서

서문

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

필수 구성 요소

워크플로 구성 옵션과 워크플로 파일을 만드는 방법을 기본적으로 이해하는 것이 좋습니다. 자세한 내용은 워크플로 작성을(를) 참조하세요.

Node.js 프로젝트용 CI 워크플로 만들기에 대한 자세한 내용은 Node.js 빌드 및 테스트을 참조하세요.

또한 다음 사항을 기본적으로 이해하는 것이 유용할 수 있습니다.

  •         [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)

  •         [AUTOTITLE](/actions/learn-github-actions/variables)

  •         [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions)

  •         [AUTOTITLE](/actions/security-guides/automatic-token-authentication)

패키지 구성 정보

          `name` 파일의 `version` 및 `package.json` 필드는 레지스트리가 패키지를 레지스트리에 연결하는 데 사용하는 고유 식별자를 만듭니다. 
          `description` 파일에 `package.json` 필드를 포함시켜 패키지 목록 페이지에 대한 요약을 추가할 수 있습니다. 자세한 내용은 npm 설명서에서 [package.json 파일 만들기](https://docs.npmjs.com/creating-a-package-json-file) 및 [Node.js 모듈 만들기](https://docs.npmjs.com/creating-node-js-modules)를 참조하세요.

로컬 .npmrc 파일이 있고 지정된 registry 값이 있는 경우 npm publish 명령은 .npmrc 파일에 구성된 레지스트리를 사용합니다. 데이터 재사용 가능한 작업.노드 설정 소개 %}

          `setup-node` 작업을 사용하여 실행기에서 설치되는 Node.js 버전을 지정할 수 있습니다.

          `publishConfig` 파일에서 `package.json` 필드를 구성하는 단계를 워크플로에 추가하는 경우, `setup-node` 작업을 사용하여 레지스트리 URL을 지정할 필요는 없지만, 패키지를 레지스트리 하나에만 게시하도록 제한을 받습니다. 자세한 내용은 npm 설명서에서 [publishConfig](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#publishconfig)를 참조하세요.

npm 레지스트리에 패키지 게시

새 릴리스를 게시할 때마다 워크플로를 트리거하여 패키지를 게시할 수 있습니다. 다음 예제의 프로세스는 published 형식의 릴리스 이벤트가 트리거될 때 실행됩니다. CI가 테스트를 통과하면 프로세스는 npm 레지스트리에 패키지를 업로드합니다. 자세한 내용은 리포지토리에서 릴리스 관리을(를) 참조하세요.

워크플로에서 npm 레지스트리에 대해 인증된 작업을 수행하려면 npm 인증 토큰을 비밀로 저장해야 합니다. 예를 들어 NPM_TOKEN이라는 레지스트리 비밀을 만듭니다. 자세한 내용은 GitHub Actions에서 비밀 사용을(를) 참조하세요.

기본적으로 npm은 name 파일의 package.json 필드를 사용하여 게시된 패키지의 이름을 확인합니다. 전역 네임스페이스에 게시하는 경우 패키지 이름만 포함하면 됩니다. 예를 들어 my-package에 https://www.npmjs.com/package/my-package라고 이름이 지정된 패키지를 게시합니다.

범위 접두사를 포함한 패키지를 게시하는 경우 package.json 파일의 이름에 범위를 포함합니다. 예를 들어, npm 범위 접두사가 "octocat"이고 패키지 이름이 "hello-world"인 경우 name 파일의 package.json은 @octocat/hello-world여야 합니다. npm 패키지에서 범위 접두사를 사용하고 패키지가 퍼블릭인 경우 npm publish --access public 옵션을 사용해야 합니다. 이 옵션은 npm에서 누군가가 의도치 않게 프라이빗 패키지를 게시하지 못하도록 방지하는 옵션입니다.

출처를 사용하여 패키지를 게시하려면 --provenance 명령에 npm publish 플래그를 포함합니다. 그러면 패키지를 빌드한 위치와 방법을 공개적으로, 확인 가능하도록 설정할 수 있으므로 패키지를 사용하는 사용자의 공급망 보안이 강화됩니다. 자세한 내용은 npm 설명서에서 출처 문 생성을 참조하세요.

이 예제에서는 NPM_TOKEN 환경 변수에 NODE_AUTH_TOKEN 비밀을 저장합니다. setup-node 작업이 .npmrc 파일을 만들 때 NODE_AUTH_TOKEN 환경 변수에서 토큰을 참조합니다.

YAML
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@v5
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        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

자격 증명을 올바르게 구성하려면 registry-url에서 https://registry.npmjs.org/을 setup-node로 설정해야 합니다.

GitHub Packages에 패키지 게시

새 릴리스를 게시할 때마다 워크플로를 트리거하여 패키지를 게시할 수 있습니다. 다음 예제의 프로세스는 published 형식의 릴리스 이벤트가 트리거될 때 실행됩니다. CI가 테스트를 통과하면 프로세스는 GitHub Packages에 패키지를 업로드합니다. 자세한 내용은 리포지토리에서 릴리스 관리을(를) 참조하세요.

대상 리포지토리 구성

          `repository` 키를 사용하여 GitHub Packages에 패키지를 연결하는 것은 선택 사항입니다. 
          `repository` 파일에 `package.json` 키를 제공하지 않도록 선택한 경우, 패키지가 게시될 때 리포지토리에 연결되지 않지만 나중에 리포지토리에 패키지를 연결하도록 선택할 수 있습니다.

그러나 repository 파일에서 package.json 키를 제공하면 해당 키의 리포지토리가 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"
  },
}

대상 리포지토리에 인증

워크플로에서 GitHub Packages 레지스트리에 대해 인증된 작업을 수행하기 위해 GITHUB_TOKEN을 사용할 수 있습니다. GITHUB_TOKEN 비밀은 워크플로의 작업이 시작될 때마다 리포지토리에 대한 액세스 토큰으로 설정됩니다. contents 권한에 대한 읽기 권한을 부여하고 packages 권한에 대한 쓰기 권한을 부여하려면 워크플로 파일에서 이 액세스 토큰에 대한 사용 권한을 설정해야 합니다. 자세한 내용은 워크플로에서 인증에 GITHUB_TOKEN 사용을(를) 참조하세요.

패키지를 다른 리포지토리에 게시하려면 대상 리포지토리의 패키지에 쓸 수 있는 권한이 있는 personal access token (classic)을 사용해야 합니다. 자세한 내용은 개인용 액세스 토큰 관리 및 GitHub Actions에서 비밀 사용을(를) 참조하세요.

워크플로 예시

이 예제에서는 GITHUB_TOKEN 환경 변수에 NODE_AUTH_TOKEN 비밀을 저장합니다. setup-node 작업이 .npmrc 파일을 만들 때 NODE_AUTH_TOKEN 환경 변수에서 토큰을 참조합니다.

YAML
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@v5
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v4
        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` 파일을 만듭니다. 
          `scope` 작업에 대해 `setup-node` 입력을 사용하는 경우 `.npmrc` 파일에는 범위 접두사가 포함됩니다. 기본적으로 `setup-node` 작업은 `.npmrc` 파일의 범위를 해당 워크플로 파일이 포함된 계정으로 설정합니다.

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

Yarn을 사용하여 패키지 게시

Yarn 패키지 관리자를 사용하는 경우 Yarn을 사용하여 패키지를 설치하고 게시할 수 있습니다.

YAML
name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        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 문서의 설정 문서를 참조하세요.