• 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 패키지들 패키지 레지스트리

특정 API 엔드포인트에 대한 npm 패키지 관리자 클라이언트의 문서를 보려면 npm API 문서를 확인하세요.

npm 또는 yarn 패키지를 만드는 방법을 배워보세요.

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

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

패키지 레지스트리로의 인증

패키지를 게시하려면 토큰이 필요합니다. 달성하려는 목표에 따라 사용 가능한 다양한 토큰이 있습니다. 자세한 내용은 토큰에 대한 지침을 확인하십시오.

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

토큰을 생성하고 나중에 사용하도록 저장하세요.

여기에 문서화되지 않은 인증 방법은 향후 제거될 수 있으니 문서화된 인증 방법 이외의 인증 방법을 사용하지 마십시오.

네이밍 컨벤션

패키지 설치 방식에 따라 네이밍 컨벤션을 준수해야 할 수 있습니다.

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

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

프로젝트 수준 또는 그룹 수준에서 패키지를 설치할 계획이라면 네이밍 컨벤션을 준수할 필요가 없습니다.

인스턴스 수준에서 패키지를 설치할 계획이라면 패키지를 범위로 설정해야 합니다. 범위된 패키지는 @로 시작하며 @owner/package-name 형식을 갖습니다. 패키지의 범위는 .npmrc 파일에서 설정하고 package.json의 publishConfig 옵션을 사용하여 설정할 수 있습니다.

• @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

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

CI/CD 파이프라인을 사용하여 패키지 게시

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

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 그룹에 속해있지 않은 경우 사용합니다.

패키지 레지스트리로의 인증

개인 프로젝트나 비공개 그룹의 패키지를 설치하려면 패키지 레지스트리에 인증해야 합니다. 프로젝트나 그룹이 공용인 경우 인증이 필요하지 않습니다.

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을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 대체하세요.

인스턴스 레벨에서 설치

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에서 유지자에서 소유자로 필요 역할이 변경됨.

패키지 레지스트리에서 npm 패키지를 찾지 못할 때, GitLab은 요청한 클라이언트가 npmjs.com으로 요청을 다시 보낼 수 있도록 HTTP 리디렉션으로 응답합니다.

관리자는 이 동작을 Continuous Integration 설정에서 비활성화할 수 있습니다.

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

개선 사항은 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

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에 도입.

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

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-tag 디렉터리을 확인합니다.
• 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 오류가 발생하는 경우

CI_JOB_TOKEN을 사용하여 다른 프로젝트의 의존성이 있는 npm 패키지를 설치하면 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 파일에서 패키지 scope가 일관되게 설정되어 있는지 확인하세요.

예를 들어, 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자를 초과하지 않도록 확인하세요.