# Node.js 패키지 게시

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

## 서문

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

## 필수 구성 요소

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

Node.js 프로젝트용 CI 워크플로 만들기에 대한 자세한 내용은 [Node.js 빌드 및 테스트](/ko/actions/tutorials/build-and-test-code/nodejs)을 참조하세요.

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

* [npm 레지스트리 작업](/ko/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
* [변수에 정보 저장](/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables)
* [GitHub Actions에서 비밀 사용](/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)
* [워크플로에서 인증에 GITHUB\_TOKEN 사용](/ko/actions/tutorials/authenticate-with-github_token)

## 패키지 구성 정보

`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` 작업을 사용하여 기본 레지스트리 및 범위를 구성하는 실행기에서 로컬 `.npmrc` 파일을 만들 수 있습니다. 또한 `setup-node` 작업은 프라이빗 레지스트리에 액세스하거나 노드 패키지를 게시하는 데 사용되는 입력으로 인증 토큰을 허용합니다. 자세한 내용은 [`setup-node`](https://github.com/actions/setup-node/)를 참조하세요.

`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 레지스트리에 패키지를 업로드합니다. 자세한 내용은 [리포지토리에서 릴리스 관리](/ko/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)을(를) 참조하세요.

워크플로에서 npm 레지스트리에 대해 인증된 작업을 수행하려면 npm 인증 토큰을 비밀로 저장해야 합니다. 예를 들어 `NPM_TOKEN`이라는 레지스트리 비밀을 만듭니다. 자세한 내용은 [GitHub Actions에서 비밀 사용](/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)을(를) 참조하세요.

기본적으로 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에서 누군가가 의도치 않게 프라이빗 패키지를 게시하지 못하도록 방지하는 옵션입니다.

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

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

```yaml copy
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@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` 파일을 만듭니다.

```shell
//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.에 업로드합니다. 자세한 내용은 [리포지토리에서 릴리스 관리](/ko/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)을(를) 참조하세요.

### 대상 리포지토리 구성

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

파일에 키를 제공 `repository` 하면 해당 키 `package.json` 의 리포지토리가 대상 npm 레지스트리 GitHub Packages로 사용됩니다. 예를 들어, 아래 `package.json`를 게시하면 `octocat/my-other-repo`GitHub 리포지토리에 `my-package`라는 이름의 패키지가 게시됩니다.

```json
{
  "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 사용](/ko/actions/tutorials/authenticate-with-github_token)을(를) 참조하세요.

패키지를 다른 리포지토리에 게시하려면 대상 리포지토리의 패키지에 쓸 수 있는 권한이 있는 패키지를 사용해야 personal access token (classic) 합니다. 자세한 내용은 [개인용 액세스 토큰 관리](/ko/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 및 [GitHub Actions에서 비밀 사용](/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)을(를) 참조하세요.

### 워크플로 예시

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

```yaml copy
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@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` 파일의 범위를 해당 워크플로 파일이 포함된 계정으로 설정합니다.

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

## Yarn을 사용하여 패키지 게시

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

```yaml copy
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@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 문서의 [설정](https://yarnpkg.com/configuration/yarnrc#npmAuthToken) 문서를 참조하세요.