npm 패키지 레지스트리
특정 API 엔드포인트에 대한 npm 패키지 관리자 클라이언트의 문서는 npm API 문서를 참조하세요.
npm 또는 yarn 패키지를 빌드하는 방법을 배워보세요.
GitLab 패키지 레지스트리에 npm 패키지를 게시하는 비디오 데모를 시청하세요.
GitLab 패키지 레지스트리에 게시
패키지 레지스트리에 대한 인증
패키지를 게시하려면 토큰이 필요합니다. 달성하려는 목표에 따라 다양한 토큰을 사용할 수 있습니다. 자세한 정보는 토큰 가이드를 참조하세요.
- 조직에서 이중 인증(2FA)을 사용하는 경우
api
로 스코프가 설정된 개인 액세스 토큰을 사용해야 합니다. - CI/CD 파이프라인을 통해 패키지를 게시하는 경우 CI 작업 토큰을 사용해야 합니다.
토큰을 생성하고 나중에 사용하려면 저장하세요.
여기에 문서화되지 않은 인증 방법을 사용하지 마십시오. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.
명명 규칙
패키지가 설치되는 방식에 따라 명명 규칙을 준수해야 할 수 있습니다.
세 가지 API 엔드포인트 중 하나를 사용하여 패키지를 설치할 수 있습니다.
- 인스턴스 수준: 서로 다른 GitLab 그룹이나 고유한 네임스페이스에 많은 npm 패키지가 있는 경우 사용합니다.
- 그룹 수준: 동일한 그룹 또는 하위 그룹의 다른 프로젝트에 많은 npm 패키지가 있는 경우 사용합니다.
- 프로젝트 수준: 몇 개의 npm 패키지가 있고 GitLab 그룹 내에 있지 않은 경우 사용합니다.
프로젝트 수준 또는 그룹 수준에서 패키지를 설치할 계획이라면 명명 규칙을 준수할 필요가 없습니다.
인스턴스 수준에서 패키지를 설치할 계획이라면 패키지에 스코프를 지정해야 합니다. 스코프된 패키지는 @
로 시작하고 @owner/package-name
과 같은 형식을 가집니다. 패키지에 대한 스코프를 .npmrc
파일과 package.json
의 publishConfig
옵션을 사용하여 설정할 수 있습니다.
-
@scope
에 사용되는 값은 패키지를 호스팅하는 프로젝트의 루트이며 패키지 자체의 소스 코드가 있는 프로젝트의 루트가 아니어야 합니다. 스코프는 소문자여야 합니다. - 패키지 이름은 원하는 대로 지정할 수 있습니다.
프로젝트 URL | 패키지 레지스트리 내 | 스코프 | 전체 패키지 이름 |
---|---|---|---|
https://gitlab.com/my-org/engineering-group/analytics
| Analytics | @my-org
| @my-org/package-name
|
네 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
파일이나 저장소에 커밋될 수 있는 다른 파일에 GitLab 토큰(또는 다른 토큰)을 직접 하드코딩하지 마십시오.
명령줄을 통한 패키지 게시
.npmrc
의 "${NPM_TOKEN}"
에 토큰을 연결하세요. your_token
을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 대체하세요.
NPM_TOKEN=your_token npm publish
이제 패키지가 패키지 레지스트리에 게시되어야 합니다.
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
작업이 실행되면 CI/CD 파이프라인에서 패키지가 패키지 레지스트리에 게시됩니다.
패키지 설치
여러 패키지가 동일한 이름과 버전을 가지고 있는 경우, 패키지를 설치할 때 가장 최근에 게시된 패키지가 검색됩니다.
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
을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 바꿉니다.
참고: npm 버전 8부터는 _authToken 매개변수에 전체 URL 대신 URI 프래그먼트를 사용할 수 있습니다. 그러나 그룹 수준 엔드포인트는 지원되지 않습니다.
인스턴스 수준에서 설치
경고: 인스턴스 수준에서 패키지를 설치하려면 해당 패키지가 네이밍 규칙을 따라 발행되어야 합니다.
-
패키지 레지스트리에 인증을 수행하세요.
-
레지스트리를 설정합니다.
npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/
-
@scope
을 해당 프로젝트의 루트 레벨 그룹으로 바꿉니다. -
your_domain_name
을 도메인 이름으로 바꿉니다. 예:gitlab.com
. -
your_token
을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 바꿉니다.
-
-
패키지를 설치합니다.
npm install @scope/my-package
그룹 수준에서 설치
- GitLab 16.0에 도입. 기본값으로 비활성화된
npm_group_level_endpoints
라는 플래그로.- GitLab 16.1에 일반 사용 가능. 기능 플래그
npm_group_level_endpoints
가 제거됨.
-
패키지 레지스트리에 인증을 수행하세요.
-
레지스트리를 설정합니다.
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로 바꿉니다.
-
-
패키지를 설치합니다.
npm install @scope/my-package
프로젝트 수준에서 설치
-
패키지 레지스트리에 인증을 수행하세요.
-
레지스트리를 설정합니다.
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로 바꿉니다.
-
-
패키지를 설치합니다.
npm install @scope/my-package
npmjs.com으로의 패키지 전달
- GitLab 12.9에서 소개되었습니다.
npm 패키지 레지스트리에서 패키지를 찾을 수 없는 경우, GitLab은 HTTP 리디렉션으로 응답하여 요청한 클라이언트가 npmjs.com에 다시 요청을 보낼 수 있도록합니다.
관리자는 지속적 통합 설정에서 이 동작을 비활성화할 수 있습니다.
그룹 소유자는 그룹의 패키지 및 레지스트리 설정에서 이 동작을 비활성화할 수 있습니다.
개선 사항은 에픽 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
오류 발생
다른 프로젝트에서 종속성이 있는 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
패키지 네이밍 규칙을 충족하지 않을 수 있습니다.
이름이 대소 문자를 포함하여 정확히 규칙을 준수하는지 확인한 후 다시 게시를 시도하세요.
패키지가 이미 존재함
패키지가 이미 동일한 루트 네임스페이스 내의 다른 프로젝트에 발행되었으며 따라서 동일한 이름으로 다시 발행할 수 없습니다.
이는 이전에 발행된 패키지가 동일한 이름을 공유하지만 버전은 공유하지 않아도 해당됩니다.
Package JSON 파일이 너무 커짐
package.json
파일이 20,000
자를 초과하지 않도록 확인하세요.
npm publish
가 npm ERR! 500 Internal Server Error - PUT
을 반환
이 오류는 GitLab 13.3.x 이후의 알려진 문제입니다. 로그에서의 오류는 다음과 같이 나옵니다:
>NoMethodError - undefined method `preferred_language' for #<Rack::Response
이는 다음과 같은 다른 오류와 함께 발생할 수 있습니다:
>Errno::EACCES","exception.message":"Permission denied
이는 일반적으로 다음 중 하나의 권한 문제입니다:
-
'packages_storage_path'
기본값/var/opt/gitlab/gitlab-rails/shared/packages/
. - 객체 스토리지를 사용하는 경우 원격 버킷.
후자의 경우, 버킷이 존재하고 GitLab이 쓰기 액세스 권한을 가지고 있는지 확인하세요.