{"meta":{"title":"Node.js 패키지 게시","intro":"이 자습서에서는 CI(연속 통합) 워크플로의 일부로 Node.js 패키지를 레지스트리에 게시하는 방법을 알아봅니다.","product":"GitHub Actions","breadcrumbs":[{"href":"/ko/actions","title":"GitHub Actions"},{"href":"/ko/actions/tutorials","title":"자습서"},{"href":"/ko/actions/tutorials/publish-packages","title":"패키지 게시"},{"href":"/ko/actions/tutorials/publish-packages/publish-nodejs-packages","title":"Node.js 패키지 게시"}],"documentType":"article"},"body":"# Node.js 패키지 게시\n\n이 자습서에서는 CI(연속 통합) 워크플로의 일부로 Node.js 패키지를 레지스트리에 게시하는 방법을 알아봅니다.\n\n## 서문\n\n이 가이드에서는 CI(연속 통합) 테스트에 통과한 후 GitHub Packages 및 npm 레지스트리에 Node.js 패키지를 게시하는 워크플로를 만드는 방법을 보여 줍니다.\n\n## 필수 구성 요소\n\n워크플로 구성 옵션과 워크플로 파일을 만드는 방법을 기본적으로 이해하는 것이 좋습니다. 자세한 내용은 [워크플로 작성](/ko/actions/learn-github-actions)을(를) 참조하세요.\n\nNode.js 프로젝트용 CI 워크플로 만들기에 대한 자세한 내용은 [Node.js 빌드 및 테스트](/ko/actions/automating-builds-and-tests/building-and-testing-nodejs)을 참조하세요.\n\n또한 다음 사항을 기본적으로 이해하는 것이 유용할 수 있습니다.\n\n* [npm 레지스트리 작업](/ko/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)\n* [변수에 정보 저장](/ko/actions/learn-github-actions/variables)\n* [GitHub Actions에서 비밀 사용](/ko/actions/security-guides/using-secrets-in-github-actions)\n* [워크플로에서 인증에 GITHUB\\_TOKEN 사용](/ko/actions/security-guides/automatic-token-authentication)\n\n## 패키지 구성 정보\n\n```\n          `name` 파일의 `version` 및 `package.json` 필드는 레지스트리가 패키지를 레지스트리에 연결하는 데 사용하는 고유 식별자를 만듭니다. \n          `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)를 참조하세요.\n```\n\n로컬 `.npmrc` 파일이 있고 지정된 `registry` 값이 있는 경우 `npm publish` 명령은 `.npmrc` 파일에 구성된 레지스트리를 사용합니다. `setup-node` 작업을 사용하여 기본 레지스트리 및 범위를 구성하는 실행기에서 로컬 `.npmrc` 파일을 만들 수 있습니다. 또한 `setup-node` 작업은 프라이빗 레지스트리에 액세스하거나 노드 패키지를 게시하는 데 사용되는 입력으로 인증 토큰을 허용합니다. 자세한 내용은 [`setup-node`](https://github.com/actions/setup-node/)를 참조하세요.\n\n```\n          `setup-node` 작업을 사용하여 실행기에서 설치되는 Node.js 버전을 지정할 수 있습니다.\n\n          `publishConfig` 파일에서 `package.json` 필드를 구성하는 단계를 워크플로에 추가하는 경우, `setup-node` 작업을 사용하여 레지스트리 URL을 지정할 필요는 없지만, 패키지를 레지스트리 하나에만 게시하도록 제한을 받습니다. 자세한 내용은 npm 설명서에서 [publishConfig](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#publishconfig)를 참조하세요.\n```\n\n## npm 레지스트리에 패키지 게시\n\n새 릴리스를 게시할 때마다 워크플로를 트리거하여 패키지를 게시할 수 있습니다. 다음 예제의 프로세스는 `published` 형식의 릴리스 이벤트가 트리거될 때 실행됩니다. CI가 테스트를 통과하면 프로세스는 npm 레지스트리에 패키지를 업로드합니다. 자세한 내용은 [리포지토리에서 릴리스 관리](/ko/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)을(를) 참조하세요.\n\n워크플로에서 npm 레지스트리에 대해 인증된 작업을 수행하려면 npm 인증 토큰을 비밀로 저장해야 합니다. 예를 들어 `NPM_TOKEN`이라는 레지스트리 비밀을 만듭니다. 자세한 내용은 [GitHub Actions에서 비밀 사용](/ko/actions/security-guides/using-secrets-in-github-actions)을(를) 참조하세요.\n\n기본적으로 npm은 `name` 파일의 `package.json` 필드를 사용하여 게시된 패키지의 이름을 확인합니다. 전역 네임스페이스에 게시하는 경우 패키지 이름만 포함하면 됩니다. 예를 들어 `my-package`에 `https://www.npmjs.com/package/my-package`라고 이름이 지정된 패키지를 게시합니다.\n\n범위 접두사를 포함한 패키지를 게시하는 경우 `package.json` 파일의 이름에 범위를 포함합니다. 예를 들어, npm 범위 접두사가 \"octocat\"이고 패키지 이름이 \"hello-world\"인 경우 `name` 파일의 `package.json`은 `@octocat/hello-world`여야 합니다. npm 패키지에서 범위 접두사를 사용하고 패키지가 퍼블릭인 경우 `npm publish --access public` 옵션을 사용해야 합니다. 이 옵션은 npm에서 누군가가 의도치 않게 프라이빗 패키지를 게시하지 못하도록 방지하는 옵션입니다.\n\n출처를 사용하여 패키지를 게시하려면 `--provenance` 명령에 `npm publish` 플래그를 포함합니다. 그러면 패키지를 빌드한 위치와 방법을 공개적으로, 확인 가능하도록 설정할 수 있으므로 패키지를 사용하는 사용자의 공급망 보안이 강화됩니다. 자세한 내용은 npm 설명서에서 [출처 문 생성](https://docs.npmjs.com/generating-provenance-statements)을 참조하세요.\n\n이 예제에서는 `NPM_TOKEN` 환경 변수에 `NODE_AUTH_TOKEN` 비밀을 저장합니다.\n`setup-node` 작업이 `.npmrc` 파일을 만들 때 `NODE_AUTH_TOKEN` 환경 변수에서 토큰을 참조합니다.\n\n```yaml copy\nname: Publish Package to npmjs\non:\n  release:\n    types: [published]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      id-token: write\n    steps:\n      - uses: actions/checkout@v6\n      # Setup .npmrc file to publish to npm\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20.x'\n          registry-url: 'https://registry.npmjs.org'\n      - run: npm ci\n      - run: npm publish --provenance --access public\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n```\n\n위의 예제에서 `setup-node` 작업은 다음 내용이 포함된 실행기에서 `.npmrc` 파일을 만듭니다.\n\n```shell\n//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}\nregistry=https://registry.npmjs.org/\nalways-auth=true\n```\n\n자격 증명을 올바르게 구성하려면 `registry-url`에서 `https://registry.npmjs.org/`을 `setup-node`로 설정해야 합니다.\n\n## GitHub Packages에 패키지 게시\n\n새 릴리스를 게시할 때마다 워크플로를 트리거하여 패키지를 게시할 수 있습니다. 다음 예제의 프로세스는 `published` 형식의 릴리스 이벤트가 트리거될 때 실행됩니다. CI가 테스트를 통과하면 프로세스는 GitHub Packages에 패키지를 업로드합니다. 자세한 내용은 [리포지토리에서 릴리스 관리](/ko/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)을(를) 참조하세요.\n\n### 대상 리포지토리 구성\n\n```\n          `repository` 키를 사용하여 GitHub Packages에 패키지를 연결하는 것은 선택 사항입니다. \n          `repository` 파일에 `package.json` 키를 제공하지 않도록 선택한 경우, 패키지가 게시될 때 리포지토리에 연결되지 않지만 나중에 리포지토리에 패키지를 연결하도록 선택할 수 있습니다.\n```\n\n그러나 `repository` 파일에서 `package.json` 키를 제공하면 해당 키의 리포지토리가 GitHub Packages의 대상 npm 레지스트리로 사용됩니다. 예를 들어 아래 `package.json`을 게시하면 `my-package`라는 이름의 패키지가 `octocat/my-other-repo` GitHub 리포지토리에 게시됩니다.\n\n```json\n{\n  \"name\": \"@octocat/my-package\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/octocat/my-other-repo.git\"\n  },\n}\n```\n\n### 대상 리포지토리에 인증\n\n워크플로에서 GitHub Packages 레지스트리에 대해 인증된 작업을 수행하기 위해 `GITHUB_TOKEN`을 사용할 수 있습니다. `GITHUB_TOKEN` 비밀은 워크플로의 작업이 시작될 때마다 리포지토리에 대한 액세스 토큰으로 설정됩니다. `contents` 권한에 대한 읽기 권한을 부여하고 `packages` 권한에 대한 쓰기 권한을 부여하려면 워크플로 파일에서 이 액세스 토큰에 대한 사용 권한을 설정해야 합니다. 자세한 내용은 [워크플로에서 인증에 GITHUB\\_TOKEN 사용](/ko/actions/security-guides/automatic-token-authentication)을(를) 참조하세요.\n\n패키지를 다른 리포지토리에 게시하려면 대상 리포지토리의 패키지에 쓸 수 있는 권한이 있는 personal access token (classic)을 사용해야 합니다. 자세한 내용은 [개인용 액세스 토큰 관리](/ko/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) 및 [GitHub Actions에서 비밀 사용](/ko/actions/security-guides/using-secrets-in-github-actions)을(를) 참조하세요.\n\n### 워크플로 예시\n\n이 예제에서는 `GITHUB_TOKEN` 환경 변수에 `NODE_AUTH_TOKEN` 비밀을 저장합니다.\n`setup-node` 작업이 `.npmrc` 파일을 만들 때 `NODE_AUTH_TOKEN` 환경 변수에서 토큰을 참조합니다.\n\n```yaml copy\nname: Publish package to GitHub Packages\non:\n  release:\n    types: [published]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      packages: write\n    steps:\n      - uses: actions/checkout@v6\n      # Setup .npmrc file to publish to GitHub Packages\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20.x'\n          registry-url: 'https://npm.pkg.github.com'\n          # Defaults to the user or organization that owns the workflow file\n          scope: '@octocat'\n      - run: npm ci\n      - run: npm publish\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n```\n          `setup-node` 작업은 실행기에서 `.npmrc` 파일을 만듭니다. \n          `scope` 작업에 대해 `setup-node` 입력을 사용하는 경우 `.npmrc` 파일에는 범위 접두사가 포함됩니다. 기본적으로 `setup-node` 작업은 `.npmrc` 파일의 범위를 해당 워크플로 파일이 포함된 계정으로 설정합니다.\n```\n\n```shell\n//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n@octocat:registry=https://npm.pkg.github.com\nalways-auth=true\n```\n\n## Yarn을 사용하여 패키지 게시\n\nYarn 패키지 관리자를 사용하는 경우 Yarn을 사용하여 패키지를 설치하고 게시할 수 있습니다.\n\n```yaml copy\nname: Publish Package to npmjs\non:\n  release:\n    types: [published]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      # Setup .npmrc file to publish to npm\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20.x'\n          registry-url: 'https://registry.npmjs.org'\n          # Defaults to the user or organization that owns the workflow file\n          scope: '@octocat'\n      - run: yarn\n      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n```\n\n게시하는 동안 레지스트리를 사용하여 인증하려면 인증 토큰도 `yarnrc.yml` 파일에 정의되어 있는지 확인합니다. 자세한 내용은 Yarn 문서의 [설정](https://yarnpkg.com/configuration/yarnrc#npmAuthToken) 문서를 참조하세요."}