Node Package Manager(npm)은 JavaScript와 Node.js의 기본 패키지 관리자입니다. 개발자는 npm으로 코드를 공유하고 재사용하며, 의존성을 관리하고 프로젝트 워크플로를 간소화합니다. GitLab에서 npm 패키지는 소프트웨어 개발 수명 주기에서 매우 중요한 역할을 합니다.

npm 엔드포인트에 대한 자세한 내용은 API를 참고합니다.

GitLab 패키지 레지스트리에 npm 패키지를 게시하는 방법을 담은 동영상 데모를 시청합니다.

패키지 레지스트리 인증#

비공개 프로젝트나 비공개 그룹에서 패키지를 게시하거나 설치하려면 패키지 레지스트리에 인증해야 합니다. 프로젝트나 그룹이 공개이면 인증하지 않아도 됩니다. 프로젝트가 내부(internal)이면 GitLab 인스턴스에 등록된 사용자여야 합니다. 익명 사용자는 내부 프로젝트에서 패키지를 가져올 수 없습니다.

인증에는 다음 중 하나를 사용할 수 있습니다.

• 범위를 api로 설정한 다음 토큰 중 하나:
  • 개인 액세스 토큰
  • 그룹 액세스 토큰
  • 프로젝트 액세스 토큰
• 범위를 read_package_registry, write_package_registry 또는 둘 다로 설정한 배포 토큰.
• CI/CD 파이프라인으로 패키지를 게시하려면 CI/CD job 토큰.

조직에서 이중 인증(2FA)을 사용하면 범위를 api로 설정한 개인 액세스 토큰을 사용해야 합니다. 자세한 내용은 토큰 관련 안내를 참고합니다.

여기에 문서화된 방법 외의 인증 방법은 사용하지 않습니다. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.

.npmrc 파일 사용#

package.json과 같은 디렉터리에 .npmrc 파일을 만들거나 편집합니다. .npmrc 파일에 다음 줄을 포함합니다.

  //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

예시:

//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

npm config set 사용#

다음 명령을 실행합니다.

npm config set -- //<domain_name>/:_authToken=<token>

npm 버전에 따라 URL을 수정해야 할 수 있습니다.

• npm 버전 7 이하에서는 엔드포인트의 전체 URL을 사용합니다.
• 버전 8 이상에서는 _authToken 파라미터에 전체 URL 대신 URI 프래그먼트를 사용할 수 있습니다. 자세한 내용은 Auth related configuration을 참고합니다.

예시:

npm config set -- //<domain_name>/api/v4/packages/npm/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken=<token>

레지스트리 URL 설정#

GitLab 패키지 레지스트리에서 패키지를 게시하거나 설치하려면 올바른 레지스트리 URL을 사용하도록 npm을 구성해야 합니다. 구성 방법과 URL 구조는 패키지를 게시하는지 설치하는지에 따라 달라집니다.

레지스트리 URL을 구성하기 전에 각 구성 방법의 적용 범위를 이해해야 합니다.

• .npmrc 파일: 구성이 해당 파일이 있는 폴더에만 적용됩니다.
• npm config set 명령: 전역 npm 구성을 수정하며, 시스템에서 실행되는 모든 npm 명령에 영향을 줍니다.
• package.json의 publishConfig: 이 구성은 해당 패키지에만 적용되며, 그 패키지를 게시할 때만 작동합니다.

패키지 게시용 설정#

패키지를 게시할 때는 프로젝트 엔드포인트를 사용합니다.

https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/

gitlab.example.com을 GitLab 인스턴스의 도메인으로, <project_id>를 프로젝트 ID로 교체합니다. 이 URL을 구성하려면 다음 방법 중 하나를 사용합니다.

@scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/

{
  "publishConfig": {
    "@scope:registry": "https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/"
  }
}

@scope를 패키지의 범위로 교체합니다.

패키지 설치용 설정#

패키지를 설치할 때는 프로젝트, 그룹 또는 인스턴스 엔드포인트를 사용할 수 있습니다. URL 구조는 그에 따라 달라집니다. 이 URL을 구성하려면 다음 방법 중 하나를 사용합니다.

gitlab.example.com, <project_id>, <group_id>, @scope를 GitLab 인스턴스와 패키지에 맞는 값으로 교체합니다.

레지스트리 URL을 구성한 다음 패키지 레지스트리에 인증할 수 있습니다.

GitLab 패키지 레지스트리에 게시#

GitLab 패키지 레지스트리에 npm 패키지를 게시하려면 인증된 상태여야 합니다.

명명 규칙#

패키지를 설치하는 방식에 따라 명명 규칙을 지켜야 할 수 있습니다.

패키지 설치에는 세 가지 API 엔드포인트 중 하나를 사용할 수 있습니다.

• 인스턴스: 여러 GitLab 그룹이나 각자의 네임스페이스에 npm 패키지가 많을 때 사용합니다.
• 그룹: 같은 그룹이나 하위 그룹에 속한 여러 프로젝트에 npm 패키지가 많을 때 사용합니다.
• 프로젝트: npm 패키지가 적고 같은 GitLab 그룹에 없을 때 사용합니다.

프로젝트나 그룹에서 패키지를 설치할 계획이면 명명 규칙을 지키지 않아도 됩니다.

인스턴스에서 패키지를 설치할 계획이면 패키지 이름에 범위를 붙여야 합니다. 범위가 지정된 패키지는 @로 시작하고 @owner/package-name 형식입니다. 패키지의 범위는 .npmrc 파일에서, 그리고 package.json의 publishConfig 옵션으로 설정할 수 있습니다.

• @scope에 사용하는 값은 패키지 자체의 소스 코드가 있는 프로젝트의 루트가 아니라, 패키지를 호스팅하는 프로젝트의 루트입니다. 범위는 소문자여야 합니다.
• 패키지 이름은 원하는 대로 지정할 수 있습니다.

자세한 내용은 Scoped packages를 참고합니다.

package.json 파일의 패키지 이름이 이 규칙과 일치하는지 확인합니다.

"name": "@my-org/package-name"

명령줄로 패키지 게시#

인증을 구성한 다음 아래 명령으로 NPM 패키지를 게시합니다.

npm publish

인증에 .npmrc 파일을 사용하면 필요한 환경 변수를 설정합니다.

NPM_TOKEN=<token> npm publish

업로드한 패키지에 package.json 파일이 두 개 이상 있으면 처음 찾은 파일만 사용하고 나머지는 무시합니다.

CI/CD 파이프라인으로 패키지 게시#

CI/CD 파이프라인으로 게시할 때는 사전 정의된 변수 ${CI_PROJECT_ID}와 ${CI_JOB_TOKEN}으로 프로젝트의 패키지 레지스트리에 인증할 수 있습니다. 이 변수로 CI/CD job 실행 중에 인증에 사용할 .npmrc 파일을 만들 수 있습니다.

package.json이 있는 GitLab 프로젝트에서 .gitlab-ci.yml 파일을 편집하거나 만듭니다. 예시:

default:
  image: node:latest

stages:
  - deploy

publish-npm:
  stage: deploy
  script:
    - echo "@scope:registry=https://${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
    - npm publish

@scope를 게시할 패키지의 범위로 교체합니다.

파이프라인의 publish-npm job이 실행되면 패키지가 패키지 레지스트리에 게시됩니다.

패키지 설치#

이름과 버전이 같은 패키지가 여러 개 있으면 패키지를 설치할 때 가장 최근에 게시된 패키지를 가져옵니다.

GitLab 프로젝트, 그룹 또는 인스턴스에서 패키지를 설치할 수 있습니다.

• 인스턴스: 여러 GitLab 그룹이나 각자의 네임스페이스에 npm 패키지가 많을 때 사용합니다.
• 그룹: 같은 GitLab 그룹에 속한 여러 프로젝트에 npm 패키지가 많을 때 사용합니다.
• 프로젝트: npm 패키지가 적고 같은 GitLab 그룹에 없을 때 사용합니다.

인스턴스에서 설치#

사전 요구 사항:

• 범위가 지정된 명명 규칙에 따라 패키지를 게시했습니다.

1. 패키지 레지스트리에 인증합니다.

2. 레지스트리를 설정합니다.

   npm config set @scope:registry https://<domain_name>.com/api/v4/packages/npm/
   

   • @scope를 패키지를 설치할 프로젝트의 최상위 그룹으로 교체합니다.
   • <domain_name>을 도메인 이름으로 교체합니다. 예를 들어 gitlab.com입니다.

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

   npm install @scope/my-package
   

그룹에서 설치#

1. 패키지 레지스트리에 인증합니다.

2. 레지스트리를 설정합니다.

   npm config set @scope:registry=https://<domain_name>/api/v4/groups/<group_id>/-/packages/npm/
   

   • @scope를 패키지를 설치할 그룹의 최상위 그룹으로 교체합니다.
   • <domain_name>을 도메인 이름으로 교체합니다. 예를 들어 gitlab.com입니다.
   • <group_id>를 그룹 홈페이지에 있는 그룹 ID로 교체합니다.

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

   npm install @scope/my-package
   

프로젝트에서 설치#

1. 패키지 레지스트리에 인증합니다.

2. 레지스트리를 설정합니다.

   npm config set @scope:registry=https://<domain_name>/api/v4/projects/<project_id>/packages/npm/
   

   • @scope를 패키지를 설치할 프로젝트의 최상위 그룹으로 교체합니다.
   • <domain_name>을 도메인 이름으로 교체합니다. 예를 들어 gitlab.com입니다.
   • <project_id>를 프로젝트 개요 페이지에 있는 프로젝트 ID로 교체합니다.

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

   npm install @scope/my-package
   

CI/CD 파이프라인 안에서 패키지 설치#

CI/CD 파이프라인 안에서 패키지를 설치할 때는 사전 정의된 변수 ${CI_PROJECT_ID}와 ${CI_JOB_TOKEN}으로 프로젝트의 패키지 레지스트리에 인증할 수 있습니다. 이 변수로 CI/CD job 실행 중에 인증에 사용할 .npmrc 파일을 만들 수 있습니다.

package.json이 있는 GitLab 프로젝트에서 .gitlab-ci.yml 파일을 편집하거나 만듭니다. 예시:

default:
  image: node:latest

stages:
  - deploy

publish-npm:
  stage: deploy
  script:
    - echo "@scope:registry=https://${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
    - npm install @scope/my-package

@scope를 설치할 패키지의 범위로, 패키지 이름도 함께 교체합니다.

앞의 예시는 프로젝트 수준 엔드포인트를 사용합니다. 그룹 수준이나 인스턴스 수준 엔드포인트를 사용하려면 그룹에서 설치 또는 인스턴스에서 설치에서 설명한 대로 레지스트리 URL과 인증 토큰 URL을 구성합니다.

npmjs.com으로 패키지 전달#

패키지 레지스트리에서 npm 패키지를 찾지 못하면 GitLab은 HTTP 리디렉션으로 응답하며, 요청한 클라이언트는 npmjs.com으로 요청을 다시 보낼 수 있습니다.

관리자는 지속적 통합 설정에서 이 동작을 비활성화할 수 있습니다.

그룹 Owner는 그룹의 Packages and registries 설정에서 이 동작을 비활성화할 수 있습니다.

개선 사항은 에픽 3608에서 추적합니다.

패키지 사용 중단 처리#

패키지를 사용 중단으로 표시하면 패키지를 가져올 때 사용 중단 경고가 표시됩니다.

사전 요구 사항:

• 패키지를 삭제할 수 있는 권한이 있습니다.
• 패키지 레지스트리에 인증되어 있습니다.

명령줄에서 다음을 실행합니다.

npm deprecate @scope/package "Deprecation message"

CLI는 @scope/package에 버전 범위도 허용합니다. 예시:

npm deprecate @scope/package "All package versions are deprecated"
npm deprecate @scope/package@1.0.1 "Only version 1.0.1 is deprecated"
npm deprecate @scope/package@"< 1.0.5" "All package versions less than 1.0.5 are deprecated"

패키지를 사용 중단으로 표시하면 상태가 deprecated로 갱신됩니다.

사용 중단 경고 제거#

패키지의 사용 중단 경고를 제거하려면 메시지에 ""(빈 문자열)를 지정합니다. 예시:

npm deprecate @scope/package ""

패키지의 사용 중단 경고를 제거하면 상태가 default로 갱신됩니다.

패키지 삭제#

사전 요구 사항:

• Maintainer 또는 Owner 권한이 있어야 합니다.

패키지를 삭제하기 전에 관련 보안 위험을 이해해야 합니다.

패키지 삭제에는 다음 중 하나를 사용할 수 있습니다.

• UI 사용.
• API 사용.

유용한 힌트#

다른 조직의 npm 패키지 설치#

GitLab 외부의 조직과 사용자에게 패키지 요청을 라우팅할 수 있습니다.

이를 위해 .npmrc 파일에 줄을 추가합니다. @my-other-org를 프로젝트 리포지터리를 소유한 네임스페이스나 그룹으로 교체하고, 해당 조직의 URL을 사용합니다. 이름은 대소문자를 구분하며 그룹이나 네임스페이스 이름과 정확히 일치해야 합니다.

@scope:registry=https://my_domain_name.com/api/v4/packages/npm/
@my-other-org:registry=https://my_domain_name.example.com/api/v4/packages/npm/

npm 메타데이터#

GitLab 패키지 레지스트리는 npm 클라이언트에 다음 속성을 노출합니다.

• name
• versions
  • name
  • version
  • deprecated
  • dependencies
  • devDependencies
  • bundleDependencies
  • peerDependencies
  • bin
  • directories
  • dist
  • engines
  • _hasShrinkwrap
  • hasInstallScript: true(이 버전에 설치 스크립트가 있는 경우)

자세한 내용은 Abbreviated version object를 참고합니다.

npm 배포 태그 추가#

새로 게시한 패키지에 배포 태그를 추가할 수 있습니다. 태그는 선택 사항이며 한 번에 하나의 패키지에만 할당할 수 있습니다.

태그 없이 패키지를 게시하면 기본적으로 latest 태그가 추가됩니다. 태그나 버전을 지정하지 않고 패키지를 설치하면 latest 태그가 사용됩니다.

지원되는 dist-tag 명령 예시:

npm publish @scope/package --tag               # Publish a package with new tag
npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package
npm dist-tag ls @scope/package                 # List all tags under the package
npm dist-tag rm @scope/package@version my-tag  # Delete a tag from the package
npm install @scope/package@my-tag              # Install a specific tag

CI/CD에서#

GitLab CI/CD job에서 npm dist-tag 명령을 실행할 때는 다음 토큰 중 하나를 사용할 수 있습니다.

• CI_JOB_TOKEN
• 배포 토큰

사전 요구 사항:

• npm 6.9.1 이상 버전이 있습니다. 그보다 낮은 버전에서는 npm 6.9.0의 버그 때문에 배포 태그 삭제가 실패합니다.

예시:

npm-deploy-job:
  script:
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc
    - npm dist-tag add @scope/package@version my-tag

npm 패키지 감사#

GitLab은 npm audit 명령을 지원하므로 패키지에 알려진 취약점이 있는지 확인할 수 있습니다.

npm audit 사용#

사전 요구 사항:

• 패키지 레지스트리 인증을 구성합니다.
• 레지스트리 URL을 설정합니다.

보안 감사를 실행하려면 다음 명령을 실행할 수 있습니다.

npm audit --registry=https://gitlab.example.com/api/v4/packages/npm/

또는 레지스트리 구성을 이미 설정했다면 다음 명령을 실행합니다.

npm audit

npm audit 명령은 의존성에 알려진 취약점이 있는지 확인하고 보고서를 제공합니다.

npm audit 워크플로#

GitLab 패키지 레지스트리를 대상으로 npm audit을 실행하면 다음 두 가지 중 하나가 발생합니다.

1. 패키지 전달이 활성화되어 있으면(기본값) GitLab은 공개 패키지와 비공개 패키지 모두의 취약점 정보를 가져오기 위해 감사 요청을 npmjs.com으로 전달합니다.
2. 패키지 전달이 비활성화되어 있으면 GitLab은 빈 결과를 반환합니다. GitLab이 독자적으로 패키지의 취약점을 스캔하지는 않습니다.

중요한 보안 고려 사항#

--registry 플래그를 사용하거나 .npmrc 파일에서 기본 레지스트리로 설정하는 방식으로 GitLab을 패키지 레지스트리로 지정하지 않으면, 감사 요청이 공개 npm 레지스트리로 전송됩니다.

이 경우 요청 본문에는 비공개 GitLab 패키지를 포함해 프로젝트의 모든 패키지 정보가 담깁니다.

비공개 패키지 정보를 GitLab 안에 유지하려면 npm audit 명령을 실행할 때 항상 GitLab 레지스트리를 지정합니다.

알려진 문제#

• 감사 결과는 패키지 전달이 활성화되어 있어야 얻을 수 있습니다. 관리자나 그룹 Owner가 전달을 비활성화하면 npm audit은 취약점 정보를 반환하지 않습니다.
• 감사 요청에는 비공개 패키지를 포함해 프로젝트의 모든 패키지 정보가 담깁니다.

지원되는 CLI 명령#

GitLab npm 리포지터리는 npm CLI(npm)와 yarn CLI(yarn)에서 다음 명령을 지원합니다.

• npm install: npm 패키지를 설치합니다.
• npm publish: npm 패키지를 레지스트리에 게시합니다.
• npm dist-tag add: npm 패키지에 dist-tag를 추가합니다.
• npm dist-tag ls: 패키지의 dist-tag를 나열합니다.
• npm dist-tag rm: dist-tag를 삭제합니다.
• npm ci: package-lock.json 파일에서 npm 패키지를 바로 설치합니다.
• npm view: 패키지 메타데이터를 표시합니다.
• npm pack: 패키지에서 tarball을 만듭니다.
• npm deprecate: 패키지의 특정 버전을 사용 중단으로 표시합니다.
• npm audit: 프로젝트 의존성의 취약점을 확인합니다.

문제 해결#

npm 로그가 올바르게 표시되지 않음#

다음과 같은 오류가 발생할 수 있습니다.

npm ERR! A complete log of this run can be found in: .npm/_logs/<date>-debug-0

.npm/_logs/ 디렉터리에 로그가 나타나지 않으면 로그를 루트 디렉터리로 복사해 그곳에서 확인할 수 있습니다.

  script:
    - npm install --loglevel verbose
    - cp -r /root/.npm/_logs/ .
  artifacts:
    paths:
      - './_logs'

npm 로그는 아티팩트로 /root/.npm/_logs/에 복사됩니다.

npm install 또는 yarn에서 404 Not Found 오류 발생#

다른 프로젝트에 의존성이 있는 npm 패키지를 CI_JOB_TOKEN으로 설치하면 404 Not Found 오류가 발생합니다. 해당 패키지와 그 모든 의존성에 접근할 수 있는 토큰으로 인증해야 합니다.

Yarn Classic으로 그룹 레지스트리에서 패키지를 설치하면 패키지 해석은 성공하지만 tarball 다운로드가 404 Not Found 오류로 실패할 수 있습니다. 그룹 엔드포인트가 반환하는 패키지 메타데이터에 프로젝트 엔드포인트를 가리키는 tarball URL이 들어 있기 때문입니다. 그룹 엔드포인트와 프로젝트 엔드포인트 양쪽에 인증 토큰을 구성해야 합니다.

//gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/:_authToken=<token>
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken=<token>

자세한 내용은 Yarn Classic이 그룹 설치에서 tarball을 가져올 때 404 Not Found를 반환함을 참고합니다.

패키지와 그 의존성이 서로 다른 프로젝트에 있지만 같은 그룹에 속한다면 그룹 배포 토큰을 사용할 수 있습니다.

//gitlab.example.com/api/v4/packages/npm/:_authToken=<group-token>
@group-scope:registry=https://gitlab.example.com/api/v4/packages/npm/

패키지와 그 의존성이 여러 그룹에 흩어져 있다면, 모든 그룹이나 개별 프로젝트에 접근할 수 있는 사용자의 개인 액세스 토큰을 사용할 수 있습니다.

//gitlab.example.com/api/v4/packages/npm/:_authToken=<personal-access-token>
@group-1:registry=https://gitlab.example.com/api/v4/packages/npm/
@group-2:registry=https://gitlab.example.com/api/v4/packages/npm/

npm publish가 기본 npm 레지스트리(registry.npmjs.org)를 대상으로 함#

package.json과 .npmrc 파일에서 패키지 범위가 일관되게 설정되어 있는지 확인합니다.

예를 들어 GitLab의 프로젝트 이름이 @scope/my-package이면 package.json 파일은 다음과 같아야 합니다.

{
  "name": "@scope/my-package"
}

그리고 .npmrc 파일은 다음과 같아야 합니다.

@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"

npm install이 npm ERR! 403 Forbidden을 반환함#

이 오류가 발생하면 다음을 확인합니다.

• 프로젝트 설정에서 패키지 레지스트리가 활성화되어 있습니다. 패키지 레지스트리는 기본적으로 활성화되어 있지만 비활성화할 수도 있습니다.
• 토큰이 만료되지 않았고 적절한 권한을 가지고 있습니다.
• 지정한 범위 안에 이름이나 버전이 같은 패키지가 이미 존재하지 않습니다.
• 범위가 지정된 패키지 URL이 슬래시로 끝납니다.
  • 올바른 예: //gitlab.example.com/api/v4/packages/npm/
  • 잘못된 예: //gitlab.example.com/api/v4/packages/npm

npm publish가 npm ERR! 400 Bad Request를 반환함#

이 오류가 발생하면 다음 문제 중 하나가 원인일 수 있습니다.

패키지 이름이 명명 규칙에 맞지 않음#

패키지 이름이 @scope/package-name 패키지 명명 규칙에 맞지 않을 수 있습니다.

대소문자를 포함해 규칙을 정확히 지키는지 확인한 다음 다시 게시합니다.

패키지가 이미 존재함#

같은 루트 네임스페이스의 다른 프로젝트에 패키지가 이미 게시되어 있으므로 같은 이름으로 다시 게시할 수 없습니다.

이전에 게시한 패키지가 이름은 같고 버전은 다른 경우에도 마찬가지입니다.

패키지 JSON 파일이 너무 큼#

package.json 파일이 20,000자를 넘지 않도록 합니다.