npm 레지스트리 작업

npm 프로젝트에 종속성으로 저장된 GitHub Packages 패키지를 GitHub Packages 게시하고 사용하도록 npm을 구성할 수 있습니다.

이 기사에서

인증 진행 중 GitHub Packages

참고

GitHub Packages은(는) personal access token (classic)을(를) 사용하는 인증만 지원합니다. 자세한 내용은 개인용 액세스 토큰 관리을(를) 참조하세요.

프라이빗, 내부, 퍼블릭 패키지를 게시, 설치, 삭제하려면 액세스 토큰이 필요합니다.

personal access token (classic)을 사용하여 GitHub Packages 또는 GitHub API에 인증할 수 있습니다. personal access token (classic)을(를) 만들 때 필요에 따라 토큰의 범위를 다르게 할당할 수 있습니다. personal access token (classic)의 패키지 관련 범위에 대한 자세한 내용은 GitHub 패키지에 대한 사용 권한 정보를 참조하세요.

GitHub Packages 워크플로 내에서 GitHub Actions 레지스트리에 인증하려면 다음을 사용할 수 있습니다.

  • 워크플로 리포지토리와 연결된 패키지를 게시하려면 GITHUB_TOKEN을 사용합니다.
  • 다른 프라이빗 리포지토리와 연결된 패키지를 설치하기 위한 최소한 read:packages 범위가 있는 personal access token (classic)(리포지토리에 패키지에 대한 읽기 액세스 권한이 부여된 경우 GITHUB_TOKEN을 사용할 수 있습니다. 패키지의 액세스 제어 및 표시 여부 구성을(를) 참조하세요).

GitHub Actions 워크플로에서 인증하기

이 레지스트리는 세분화된 권한을 지원합니다. 세분화된 권한을 지원하는 레지스트리는 GitHub Actions 워크플로가 personal access token을(를) 사용하여 레지스트리에 인증하는 경우, GITHUB_TOKEN로 워크플로를 업데이트하는 것을 권장합니다. personal access token로 레지스트리에 인증하는 워크플로를 업데이트하는 방법에 대한 지침은 GitHub Actions를 사용하여 패키지 게시 및 설치를 참조하세요.

참고

GitHub Actions 워크플로에서 REST API를 사용하여 패키지를 삭제하고 복원하는 기능은 현재 공개 미리 보기 버전이며 변경될 수 있습니다.

토큰이 패키지에 대해 admin 권한이 있는 경우, GitHub Actions 워크플로에서 GITHUB_TOKEN로 REST API를 사용하여 패키지를 삭제하거나 복원할 수 있습니다. 워크플로를 사용하여 패키지를 게시하는 리포지토리와 패키지에 명시적으로 연결한 리포지토리에는 리포지토리의 패키지에 대한 admin 권한이 자동으로 부여됩니다.

GITHUB_TOKEN에 대한 자세한 내용은 워크플로에서 인증에 GITHUB_TOKEN 사용을(를) 참조하세요. 작업에서 레지스트리를 사용하는 모범 사례에 대한 자세한 내용은 안전 사용 참조를 참조하세요.

GitHub Codespaces및 GitHub Actions에 대한 패키지의 액세스 권한을 독립적으로 부여하도록 선택할 수도 있습니다. 자세한 내용은 패키지의 액세스 제어 및 표시 여부 구성 및 패키지의 액세스 제어 및 표시 여부 구성을(를) 참조하세요.

personal access token를 사용하여 인증하기

적절한 범위의personal access token (classic)으로 GitHub Packages에서 패키지를 게시하고 설치해야 합니다. 자세한 내용은 GitHub 패키지 소개을(를) 참조하세요.

npm을 사용해 GitHub Packages에 인증하려면, 사용자별 ~/.npmrc 파일을 편집하여 personal access token (classic)를 포함하거나 사용자 이름과 personal access token를 사용해 명령줄에서 npm에 로그인하면 됩니다.

~/.npmrc 파일에 personal access token (classic)을(를) 추가하여 인증하려면, 다음 줄이 포함되도록 프로젝트의 ~/.npmrc 파일을 편집하세요. 여기서 TOKEN은 사용자의 personal access token으로 바꾸세요. ~/.npmrc 파일이 없는 경우에는 새 파일을 만듭니다.

//npm.pkg.github.com/:_authToken=TOKEN

npm에 로그인하여 인증하려면 npm login 명령을 사용하고, USERNAME은 GitHub 사용자 이름으로, TOKEN은 personal access token (classic)로, PUBLIC-EMAIL-ADDRESS는 이메일 주소로 바꾸세요.

npm CLI 버전 9 이상에서 명령줄을 사용하여 프라이빗 레지스트리에 로그인 또는 로그아웃하는 경우 브라우저를 통해 기본 로그인 흐름을 사용하는 대신 프롬프트에서 인증 세부 정보를 읽는 --auth-type=legacy 옵션을 사용해야 합니다. 자세한 내용은 npm-login를 참조하세요.

GitHub Packages가 npm 사용 시 기본 패키지 레지스트리가 아니고 npm audit 명령을 사용하려는 경우, GitHub Packages에 인증할 때 패키지를 호스팅하는 네임스페이스(패키지 범위가 지정된 개인 계정 또는 조직 또는 패키지가 호스팅된 리포지토리를 소유한 주체)와 함께 --scope 플래그를 사용하는 것이 좋습니다.

$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN

패키지 게시

참고

  • 패키지 이름 및 범위는 소문자만 사용해야 합니다.
  • npm 버전의 tarball은 256MB보다 작아야 합니다.

레지스트리는 GitHub Packages 조직 또는 개인 계정 내에 npm 패키지를 저장하고 패키지를 리포지토리와 연결할 수 있습니다. 리포지토리에서 사용 권한을 상속할지 또는 리포지토리와 독립적으로 세분화된 권한을 설정할지 선택할 수 있습니다.

패키지를 처음 게시할 때 기본 표시 여부는 프라이빗입니다. 표시 유형 또는 액세스 권한을 변경하려면 패키지의 액세스 제어 및 표시 여부 구성을(를) 참조하세요. 게시된 패키지를 리포지토리와 연결하는 방법에 대한 자세한 내용은 리포지토리를 패키지에 연결을 참조하세요.

repository 파일에 package.json 필드를 포함하면 패키지가 게시되는 즉시 패키지를 리포지토리에 연결할 수 있습니다. 이 메서드를 사용하여 여러 패키지를 동일한 리포지토리에 연결할 수도 있습니다. 자세한 내용은 동일한 리포지토리에 여러 패키지 게시를 참조하세요.

참고

리포지토리에 연결된 패키지를 게시하는 경우, 패키지는 자동으로 연결된 리포지토리의 액세스 권한을 상속받고, 조직에서 액세스 권한의 자동 상속을 사용하지 않도록 설정하지 않은 한 연결된 리포지토리의 GitHub Actions 워크플로에 패키지에 대한 액세스 권한이 자동으로 부여됩니다. 자세한 내용은 패키지의 액세스 제어 및 표시 여부 구성을(를) 참조하세요.

프로젝트의 로컬 .npmrc 파일을 사용하거나 publishConfig의 package.json 옵션을 사용하여 프로젝트에 대한 범위 매핑을 설정할 수 있습니다. GitHub Packages 는 범위가 지정된 npm 패키지만 지원합니다. 범위가 지정된 패키지에는 @NAMESPACE/PACKAGE-NAME 형식의 이름이 있습니다. 범위가 지정된 패키지는 항상 @ 기호로 시작합니다. 범위가 지정된 이름을 사용하려면 package.json의 이름을 업데이트해야 할 수 있습니다. 예를 들어 사용자가 octocat이고 패키지 이름이 test(으)로 지정된 경우 범위가 지정된 패키지 이름은 "name": "@octocat/test"과(와) 같이 할당됩니다.

패키지를 게시한 후 GitHub에서 패키지를 볼 수 있습니다. 자세한 내용은 패키지 보기을(를) 참조하세요.

로컬 .npmrc 파일을 사용하여 패키지 게시

.npmrc 파일을 사용하여 프로젝트에 대한 범위 매핑을 구성할 수 있습니다. .npmrc 파일에서 URL 및 계정 소유자를 GitHub Packages 사용하므로 GitHub Packages 패키지 요청을 라우팅할 위치를 알 수 있습니다. .npmrc 파일을 사용하면 다른 개발자가 GitHub Packages 대신 npmjs.org에 실수로 패키지를 게시하는 일을 방지할 수 있습니다.

  1. GitHub Packages에 인증합니다. 자세한 내용은 GitHub Packages에 인증을 참조하세요.

  2. package.json 파일과 동일한 디렉터리에서 GitHub Packages URL 및 패키지를 호스팅하는 네임스페이스를 지정하는 행을 포함하도록 .npmrc 파일을 만들거나 편집합니다. NAMESPACE을 패키지의 범위로 지정할 사용자 또는 조직 계정의 이름으로 변경합니다.

    @NAMESPACE:registry=https://npm.pkg.github.com

  3. GitHub Packages에서 프로젝트를 찾을 수 있는 리포지토리에 .npmrc 파일을 추가합니다. 자세한 내용은 리포지토리에 파일 추가을(를) 참조하세요.

  4. 프로젝트의 package.json에서 패키지 이름을 확인합니다. name 필드에는 패키지의 범위와 이름이 포함되어야 합니다. 예를 들어, 패키지 이름이 "test"이고 이를 "My-org" GitHub 조직에 게시하는 경우, package.json에 있는 name 필드는 @my-org/test여야 합니다.

  5. 프로젝트의 package.json에 있는 repository 필드를 확인합니다. repository 필드는 GitHub 리포지토리의 URL과 일치해야 합니다. 예를 들어 리포지토리 URL이 github.com/my-org/test인 경우 리포지토리 필드는 https://github.com/my-org/test.git이어야 합니다.

  6. 패키지를 게시합니다.

    npm publish

publishConfig을(를) 사용하여 package.json 파일에 패키지 게시

publishConfig 파일의 package.json 요소를 사용하여 패키지를 게시할 레지스트리를 지정할 수 있습니다. 자세한 내용은 npm 설명서에서 publishConfig를 참조하세요.

  1. 패키지의 package.json 파일을 편집하고 publishConfig 항목을 포함합니다.

    "publishConfig": {
  "registry": "https://npm.pkg.github.com"
},

  2. 프로젝트의 package.json에 있는 repository 필드를 확인합니다. repository 필드는 GitHub 리포지토리의 URL과 일치해야 합니다. 예를 들어 리포지토리 URL이 github.com/my-org/test인 경우 리포지토리 필드는 https://github.com/my-org/test.git이어야 합니다.

  3. 패키지를 게시합니다.

    npm publish

동일한 리포지토리에 여러 패키지 게시

여러 패키지를 게시하고 동일한 리포지토리에 연결 하려면 각 패키지의 GitHub 파일 필드에 리포지 repository 토리의 URL을 package.json 포함할 수 있습니다. 자세한 내용은 npm 설명서에서 package.json 파일 만들기 및 Node.js 모듈 만들기를 참조하세요.

리포지토리의 URL이 올바른지 확인하려면 게시 REPOSITORY 하려는 패키지가 포함된 리포지토리의 이름과 리포지토리를 소유한 개인 계정 또는 조직의 OWNER 이름으로 바꿉 GitHub 다.

GitHub Packages는 패키지 이름을 기반으로 하는 대신 URL에 따라 리포지토리와 일치합니다.

"repository":"https://github.com/OWNER/REPOSITORY",

패키지 설치

프로젝트의 package.json 파일에 패키지를 종속성으로 추가하여 GitHub Packages에서 패키지를 설치할 수 있습니다. 프로젝트에서 package.json을 사용하는 방법에 대한 자세한 내용은 npm 설명서의 package.json 작업을 참조하세요.

기본적으로 한 조직의 패키지를 추가할 수 있습니다. 자세한 내용은 다른 조직에서 패키지 설치를 참조하세요.

패키지를 설치하는 모든 요청이 .npmrc 통과 GitHub Packages되도록 프로젝트에 파일을 추가해야 합니다. 모든 패키지 요청을 GitHub Packages를 통해 라우팅하면 _npmjs.org_의 범위가 지정된 패키지와 범위가 지정되지 않은 패키지를 모두 사용할 수 있습니다. 자세한 내용은 npm 설명서의 npm-scope를 참조하세요.

  1. GitHub Packages에 인증합니다. 자세한 내용은 GitHub Packages에 인증을 참조하세요.

  2. package.json 파일과 동일한 디렉터리에서 GitHub Packages URL 및 패키지를 호스팅하는 네임스페이스를 지정하는 행을 포함하도록 .npmrc 파일을 만들거나 편집합니다. NAMESPACE을 패키지의 범위로 지정할 사용자 또는 조직 계정의 이름으로 변경합니다.

    @NAMESPACE:registry=https://npm.pkg.github.com

  3. GitHub Packages에서 프로젝트를 찾을 수 있는 리포지토리에 .npmrc 파일을 추가합니다. 자세한 내용은 리포지토리에 파일 추가을(를) 참조하세요.

  4. 설치 중인 패키지를 사용하도록 프로젝트의 package.json을(를) 구성합니다. 패키지 종속성을 package.json 파일에 GitHub Packages추가하려면 전체 범위 패키지 이름(예: @my-org/server.)을 지정합니다. npmjs.com 패키지의 경우 전체 이름(예: @babel/core 또는 lodash)을 지정합니다. ORGANIZATION_NAME/PACKAGE_NAME을(를) 패키지 종속성으로 교체합니다.

    {
  "name": "@my-org/server",
  "version": "1.0.0",
  "description": "Server app that uses the ORGANIZATION_NAME/PACKAGE_NAME package",
  "main": "index.js",
  "author": "",
  "license": "MIT",
  "dependencies": {
    "ORGANIZATION_NAME/PACKAGE_NAME": "1.0.0"
  }
}

  5. 패키지를 설치합니다.

npm install

다른 조직에서 패키지 설치

기본적으로 하나의 조직에 속한 GitHub Packages 패키지만 사용할 수 있습니다. 패키지 요청을 여러 조직 및 사용자에게 라우팅하려는 경우 파일에.npmrc 추가 줄을 프로젝트가NAMESPACE 포함된 리포지토리를 소유하는 패키지의 범위가 지정된개인 계정 또는 조직의

@NAMESPACE:registry=https://npm.pkg.github.com
@NAMESPACE:registry=https://npm.pkg.github.com