• GitLab 패키지 레지스트리에 게시하기
  • 패키지 레지스트리에 대한 인증
  • 명명 규칙
• 명령줄을 통한 패키지 게시
  • .npmrc를 통한 인증
  • 커맨드라인을 통한 패키지 배포
• CI/CD 파이프라인을 사용한 패키지 배포
• 패키지 설치
  • 패키지 레지스트리에 인증
  • 인스턴스에서 설치
  • 그룹에서 설치
  • 프로젝트에서 설치
  • npmjs.com으로의 패키지 포워딩
• 패키지 비활성화
  • 비활성화 경고 제거
• 유용한 힌트
  • 다른 조직의 npm 패키지 설치
  • npm 메타데이터
  • npm 배포 태그 추가
    • CI/CD에서
  • 지원되는 CLI 명령어
• 문제 해결
  • npm install 또는 yarn에서 404 Not Found 오류 발생
  • npm publish는 기본 npm 레지스트리(registry.npmjs.org)를 대상으로 합니다
  • npm install이 npm ERR! 403 Forbidden을 반환합니다
  • npm publish가 npm ERR! 400 Bad Request를 반환합니다
  • 패키지 이름이 명명 규칙을 충족하지 않음
  • 패키지가 이미 존재함
  • 패키지 JSON 파일이 너무 큼

패키지 레지스트리의 npm 패키지

npm 패키지 관리자 클라이언트가 사용하는 특정 API 엔드포인트의 문서는 npm API 문서를 참조하세요.

npm 또는 yarn 패키지를 빌드하는 방법을 알아보세요.

GitLab 패키지 레지스트리에 npm 패키지를 게시하는 방법에 대한 비디오 데모를 시청하세요.

GitLab 패키지 레지스트리에 게시하기

패키지 레지스트리에 대한 인증

패키지를 게시하려면 토큰이 필요합니다. 달성하려는 목표에 따라 다양한 토큰이 있습니다. 자세한 내용은 토큰에 대한 가이드를 참조하세요.

• 조직에서 이중 인증(2FA)을 사용하는 경우, api 범위로 설정된 개인 액세스 토큰을 사용해야 합니다.
• CI/CD 파이프라인을 통해 패키지를 게시하는 경우, CI 작업 토큰을 사용해야 합니다.

토큰을 생성하고 과정에서 나중에 사용할 수 있도록 저장하세요.

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

명명 규칙

패키지가 설치되는 방식에 따라 명명 규칙을 준수해야 할 수 있습니다.

패키지를 설치하기 위해 3개의 API 엔드포인트 중 하나를 사용할 수 있습니다:

• Instance: 서로 다른 GitLab 그룹에 있거나 자체 네임스페이스에 있는 많은 npm 패키지가 있는 경우 사용하세요.
• Group: 동일한 그룹 또는 하위 그룹의 서로 다른 프로젝트에 많은 npm 패키지가 있는 경우 사용하세요.
• Project: npm 패키지가 적고 동일한 GitLab 그룹에 없는 경우 사용하세요.

프로젝트 또는 그룹에서 패키지를 설치할 계획이라면,
명명 규칙을 준수할 필요가 없습니다.

인스턴스에서 패키지를 설치할 계획이라면, 패키지를
scope로 이름을 지정해야 합니다.
Scoped package는 @로 시작하며 형식은
@owner/package-name입니다. 패키지의 scope는 .npmrc 파일에서 설정할 수 있으며 package.json의 publishConfig 옵션을 사용합니다.

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

package.json 파일의 패키지 이름이 이 규칙과 일치하는지 확인하세요:

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

명령줄을 통한 패키지 게시

.npmrc를 통한 인증

package.json과 동일한 디렉토리에 .npmrc 파일을 생성하거나 수정하세요. .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}"  

• @scope를 패키지를 게시할 프로젝트의 루트 수준 그룹으로 바꾸세요.
• your_domain_name을 gitlab.com과 같은 도메인 이름으로 바꾸세요.
• your_project_id를 프로젝트 개요 페이지에서 찾은 프로젝트 ID로 바꾸세요.
• "${NPM_TOKEN}"은 나중에 과정에서 생성한 토큰과 연결됩니다.

커맨드라인을 통한 패키지 배포

.npmrc에서 "${NPM_TOKEN}"과 함께 토큰을 연결하십시오. your_token을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 바꿉니다.

NPM_TOKEN=your_token npm publish

이제 패키지가 패키지 레지스트리에 게시되어야 합니다.

업로드된 패키지에 package.json 파일이 여러 개 있으면, 발견된 첫 번째 파일만 사용되고 나머지는 무시됩니다.

CI/CD 파이프라인을 사용한 패키지 배포

CI/CD 파이프라인을 사용하여 게시할 때, 프로젝트의 패키지 레지스트리에 인증하기 위해 미리 정의된 변수 ${CI_PROJECT_ID} 및 ${CI_JOB_TOKEN}을 사용할 수 있습니다. 우리는 이 변수를 사용하여 CI/CD 작업 실행 중 인증을 위한 .npmrc 파일을 생성합니다.

경고:

.npmrc 파일을 생성할 때, ${CI_SERVER_HOST} 뒤에 기본 포트를 지정하지 마십시오.

예를 들어 http로 시작하는 URL의 경우 80, https로 시작하는 URL의 경우 443입니다.

package.json이 포함된 GitLab 프로젝트에서 .gitlab-ci.yml 파일을 편집하거나 생성하십시오. 예를 들어:

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 작업이 파이프라인에서 실행될 때 패키지가 패키지 레지스트리에 게시됩니다.

패키지 설치

동일한 이름과 버전을 가진 패키지가 여러 개 있는 경우, 패키지를 설치할 때 가장 최근에 게시된 패키지가 검색됩니다.

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

• 인스턴스: 서로 다른 GitLab 그룹 또는 자체 네임스페이스에 여러 npm 패키지가 있는 경우 사용합니다.
• 그룹: 동일한 GitLab 그룹의 서로 다른 프로젝트에 여러 npm 패키지가 있는 경우 사용합니다.
• 프로젝트: npm 패키지가 적고 같은 GitLab 그룹에 속하지 않는 경우 사용합니다.

패키지 레지스트리에 인증

비공개 프로젝트나 비공식 그룹에서 패키지를 설치하려면 패키지 레지스트리에 인증해야 합니다.

프로젝트나 그룹이 공개인 경우 인증이 필요하지 않습니다.

프로젝트가 내부인 경우, GitLab 인스턴스에 등록된 사용자여야 합니다.

익명 사용자는 내부 프로젝트에서 패키지를 가져올 수 없습니다.

npm으로 인증하려면:

npm config set -- //your_domain_name/:_authToken=your_token

npm 버전 7 이하인 경우, 엔드포인트의 전체 URL을 사용하십시오.

설치하는 경우:

• 인스턴스에서:

  npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token
  

• 그룹에서:

  npm config set -- //your_domain_name/api/v4/groups/your_group_id/-/packages/npm/:_authToken=your_token
  

• 프로젝트에서:

  npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token
  

이 예제에서:

• your_domain_name을 예를 들어 gitlab.com과 같은 도메인 이름으로 교체하십시오.
• your_group_id를 그룹의 홈 페이지에서 찾을 수 있는 그룹 ID로 교체하십시오.
• your_project_id를 프로젝트 개요 페이지에서 찾을 수 있는 프로젝트 ID로 교체하십시오.
• your_token을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 교체하십시오.

참고:

npm 버전 8부터는 _authToken 매개변수에 전체 URL 대신 URI 조각을 사용할 수 있습니다. 그러나 그룹 전용 엔드포인트는 지원되지 않습니다.

인스턴스에서 설치

경고:
패키지를 인스턴스에서 설치하려면, 패키지가 스코프가 지정된 이름 규칙에 따라 게시되어야 합니다.

1. 패키지 레지스트리에 인증하기.

2. 레지스트리 설정

   npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/
   

   • @scope를 패키지를 설치할 프로젝트의 루트 레벨 그룹으로 바꾸세요.
   • your_domain_name을 여러분의 도메인 이름으로 바꾸세요. 예: gitlab.com.
   • your_token을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰, 또는 개인 액세스 토큰으로 바꾸세요.

3. 패키지 설치

   npm install @scope/my-package
   

그룹에서 설치

• GitLab 16.0에서 npm_group_level_endpoints라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 16.1에서 일반 사용 가능. 기능 플래그 npm_group_level_endpoints가 제거되었습니다.

1. 패키지 레지스트리에 인증하기.

2. 레지스트리 설정

   npm config set @scope:registry=https://your_domain_name/api/v4/groups/your_group_id/-/packages/npm/
   

   • @scope를 패키지를 설치할 그룹의 루트 레벨 그룹으로 바꾸세요.
   • your_domain_name을 여러분의 도메인 이름으로 바꾸세요. 예: gitlab.com.
   • your_group_id를 그룹 홈페이지에서 찾아볼 수 있는 그룹 ID로 바꾸세요.

3. 패키지 설치

   npm install @scope/my-package
   

프로젝트에서 설치

1. 패키지 레지스트리에 인증하기.

2. 레지스트리 설정

   npm config set @scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
   

   • @scope를 패키지를 설치할 프로젝트의 루트 레벨 그룹으로 바꾸세요.
   • your_domain_name을 여러분의 도메인 이름으로 바꾸세요. 예: gitlab.com.
   • your_project_id를 프로젝트 개요 페이지에서 찾을 수 있는 프로젝트 ID로 바꾸세요.

3. 패키지 설치

   npm install @scope/my-package
   

npmjs.com으로의 패키지 포워딩

• GitLab 12.9에서 도입되었습니다.
• 요구되는 역할이 변경되었습니다. GitLab 17.0에서 Maintainer에서 Owner로 변경되었습니다.

npm 패키지가 패키지 레지스트리에서 발견되지 않을 경우, GitLab은 HTTP 리다이렉트를 응답하여 요청하는 클라이언트가 npmjs.com에 요청을 재전송할 수 있도록 합니다.

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

그룹 소유자는 그룹 패키지 및 레지스트리 설정에서 이 동작을 비활성화할 수 있습니다.

개선 사항은 epic 3608에서 추적됩니다.

패키지 비활성화

• GitLab 16.0에서 도입됨.

패키지를 비활성화할 수 있으며, 패키지를 가져올 때 비활성화 경고가 표시됩니다.

사전 조건:

• 패키지를 삭제할 때와 동일한 권한.
• 패키지 레지스트리에 인증됨.

명령줄에서 다음을 실행하세요:

npm deprecate @scope/package "비활성화 메시지"

CLI는 @scope/package에 대한 버전 범위도 허용합니다. 예를 들어:

npm deprecate @scope/package "모든 패키지 버전이 비활성화되었습니다"
npm deprecate @scope/package@1.0.1 "오직 버전 1.0.1만 비활성화되었습니다"
npm deprecate @scope/package@"< 1.0.5" "1.0.5보다 작은 모든 패키지 버전이 비활성화되었습니다"

비활성화 경고 제거

패키지의 비활성화 경고를 제거하려면 메시지에 대해 "" (빈 문자열)를 지정하세요. 예를 들어:

npm deprecate @scope/package ""

유용한 힌트

다른 조직의 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.

npm 배포 태그 추가

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

태그 없이 패키지를 게시하면 기본적으로 latest 태그가 추가됩니다.

태그나 버전을 지정하지 않고 패키지를 설치하면 latest 태그가 사용됩니다.

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

npm publish @scope/package --tag               # 새 태그로 패키지 게시
npm dist-tag add @scope/package@version my-tag # 기존 패키지에 태그 추가
npm dist-tag ls @scope/package                 # 패키지 아래의 모든 태그 나열
npm dist-tag rm @scope/package@version my-tag  # 패키지에서 태그 삭제
npm install @scope/package@my-tag              # 특정 태그 설치

CI/CD에서

• GitLab 15.10에서 도입됨.

npm dist-tag 명령을 GitLab CI/CD 작업에서 실행하기 위해 CI_JOB_TOKEN 또는 배포 토큰을 사용할 수 있습니다. 예를 들어:

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 6.9.0에서 발생한 버그로 인해 배포 태그 삭제가 실패합니다. npm 버전이 6.9.1 이상인지 확인하세요.

지원되는 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-tags를 나열합니다.
• npm dist-tag rm: dist-tag를 삭제합니다.
• npm ci: package-lock.json 파일에서 직접 npm 패키지를 설치합니다.
• npm view: 패키지 메타데이터를 표시합니다.
• npm pack: 패키지에서 tarball을 생성합니다.
• npm deprecate: 패키지의 버전을 더 이상 사용되지 않도록 설정합니다.

문제 해결

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

다른 프로젝트에서 종속성과 함께 npm 패키지를 설치하기 위해 CI_JOB_TOKEN을 사용하면 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자를 초과하지 않는지 확인하세요.