Node.js 패키지 게시

소개

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

필수 조건

워크플로 구성 옵션과 워크플로 파일을 만드는 방법을 기본적으로 이해하는 것이 좋습니다. 자세한 내용은 "Github Actions 알아보기"을 참조하세요.

Node.js 프로젝트에 대한 CI 워크플로를 만드는 방법에 대한 자세한 내용은 "Node.js 빌드 및 테스트.

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

패키지 구성 정보

package.json 파일의 name 및 version 필드는 레지스트리가 패키지를 레지스트리에 연결하는 데 사용하는 패키지의 고유 식별자를 만듭니다. package.json 파일에 description필드를 포함하여 패키지 목록 페이지에 대한 요약을 추가할 수 있습니다. 자세한 내용은 npm 설명서에서 “package.json 파일 만들기” 및 “Node.js 모듈 만들기”를 참조하세요.

로컬 .npmrc 파일이 있고 지정된 registry 값이 있는 경우 npm publish 명령은 .npmrc 파일에 구성된 레지스트리를 사용합니다. setup-node 작업을 사용하여 기본 레지스트리 및 범위를 구성하는 실행기에서 로컬 .npmrc 파일을 만들 수 있습니다. 또한 setup-node 작업은 프라이빗 레지스트리에 액세스하거나 노드 패키지를 게시하는 데 사용되는 입력으로 인증 토큰을 허용합니다. 자세한 내용은 setup-node을(를) 참조하세요.

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

package.json 파일에서 publishConfig 필드를 구성하는 단계를 워크플로에서 추가하는 경우 setup-node 작업을 사용하여 레지스트리 URL을 지정할 필요는 없지만 패키지를 레지스트리 하나에 게시하도록 제한됩니다. 자세한 내용은 npm 설명서에서 “publishConfig”를 참조하세요.

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

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

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

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

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

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

YAML

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v3
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        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/로 설정해야 합니다.

GitHub Packages에 패키지 게시

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

대상 리포지토리 구성

repository 키를 사용하여 GitHub Packages에 패키지를 연결하는 것은 선택 사항입니다. repositorypackage.json파일에서 키를 제공하지 않도록 선택하면 GitHub Packages는 package.json 파일의 name 필드에 지정한 GitHub 리포지토리에서 패키지를 게시합니다. 예를 들어 @my-org/test라는 패키지가 my-org/test GitHub 리포지토리에 게시됩니다. repository 키에 지정된 url이 유효하지 않은 경우 패키지는 계속 게시될 수 있지만 의도한 대로 리포지토리 원본에 연결되지는 않습니다.

그러나 package.json 파일에서 repository 키를 제공하면 해당 키의 리포지토리가 GitHub Packages의 대상 npm 레지스트리로 사용됩니다. 예를 들어 아래 package.json을 게시하면 octocat/my-other-repo GitHub 리포지토리에 my-package라는 패키지가 게시됩니다. 게시되면 리포지토리 원본만 업데이트되고 패키지는 대상 리포지토리에서 사용 권한을 상속하지 않습니다.

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

대상 리포지토리에 인증

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

패키지를 다른 리포지토리에 게시하려면 대상 리포지토리의 패키지에 쓸 수 있는 권한이 있는 personal access token (classic)을(를) 사용해야 합니다. 자세한 내용은 "개인용 액세스 토큰 만들기" 및 "암호화된 비밀.

예제 워크플로

이 예제에서는 NODE_AUTH_TOKEN 환경 변수에 GITHUB_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@v3
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v3
        with:
          node-version: '16.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

yarn을 사용하여 패키지 게시

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

YAML

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

Node.js 패키지 게시

이 문서의 내용