npm 패키지 패키지 레지스트리
npm 패키지 관리자 클라이언트가 사용하는 특정 API 엔드포인트에 대한 문서를 보려면 npm API 문서를 참조하십시오.
npm 또는 yarn 패키지를 빌드하는 방법을 배우세요.
npm 패키지를 GitLab 패키지 레지스트리에 게시하는 방법을 보려면 비디오 데모를 시청하세요.
GitLab 패키지 레지스트리에 발행
패키지 레지스트리에 대한 인증
패키지를 게시하려면 토큰이 필요합니다. 달성하려는 목표에 따라 사용할 수 있는 다양한 토큰이 있습니다. 자세한 정보는 토큰에 관한 지침을 참조하십시오.
- 조직에서 이중 인증(2FA)을 사용하는 경우
api로 범위가 설정된 개인 액세스 토큰을 사용해야 합니다. - CI/CD 파이프라인을 통해 패키지를 게시하는 경우 CI 작업 토큰을 사용해야 합니다.
토큰을 생성하고 나중에 프로세스에서 사용할 수 있도록 저장하십시오.
여기에 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.
네이밍 컨벤션
패키지가 설치된 방식에 따라 네이밍 규칙을 준수해야 할 수도 있습니다.
다음 세 가지 API 엔드포인트 중 하나를 사용할 수 있습니다.
- 인스턴스: 서로 다른 GitLab 그룹이나 해당 자체 네임스페이스에 많은 npm 패키지가 있는 경우 사용합니다.
- 그룹: 동일한 그룹 또는 하위 그룹의 다른 프로젝트에 많은 npm 패키지가 있는 경우 사용합니다.
- 프로젝트: 몇 개의 npm 패키지가 있고 GitLab 그룹에 속하지 않은 경우 사용합니다.
패키지를 프로젝트나 그룹에서 설치할 계획이라면 네이밍 규칙을 준수할 필요는 없습니다.
패키지를 인스턴스에서 설치할 계획이라면 패키지를 scope로 명명해야 합니다. Scoped 패키지는 @로 시작하며, @owner/package-name 형식을 갖습니다. 패키지에 대한 scope는 .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
패키지가 이제 패키지 레지스트리에 게시되어야 합니다.
게시된 패키지에 package.json 파일 이상이 있다면, 첫 번째로 발견된 것만 사용되고 나머지는 무시됩니다.
CI/CD 파이프라인을 통한 패키지 게시
CI/CD 파이프라인을 사용하여 게시하는 경우 미리 정의된 변수 ${CI_PROJECT_ID} 및 ${CI_JOB_TOKEN}을 사용하여 프로젝트의 패키지 레지스트리에 인증할 수 있습니다. 이러한 변수를 사용하여 실행 중에 CI/CD 작업에서 .npmrc 파일을 생성합니다.
경고:
기본 포트(예: http로 시작하는 URL의 경우 80, https로 시작하는 URL의 경우 443)와 같은 기본 포트인 경우 ${CI_SERVER_HOST} 뒤에 포트를 지정하지 마십시오.
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
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 조각을 사용
할 수 있습니다. 그러나 그룹별 엔드포인트는 지원되지 않습니다.
인스턴스에서 설치
경고: 인스턴스에서 패키지를 설치하려면 패키지는 스코프 네이밍 컨벤션을 따라 발행되어야 합니다.
-
패키지 레지스트리에 인증합니다.
-
레지스트리 설정
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에서 도입. 기본 설정은 비활성화됨.
- 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으로 패키지 전달
패키지 레지스트리에서 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-
versionsnameversiondeprecateddependenciesdevDependenciesbundleDependenciespeerDependenciesbindirectoriesdistengines_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 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 패키지에 태그 추가 -
npm dist-tag ls: 패키지의 태그 나열 -
npm dist-tag rm: 태그 삭제 -
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자를 초과하지 않도록 확인하세요.
도움말