패키지 레지스트리의 npm 패키지
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Node Package Manager(npm)은 JavaScript 및 Node.js의 기본 패키지 관리자입니다. npm 엔드포인트에 대한 자세한 내용은 API를 참조하세요. GitLab 패키지 레지스트리에 npm 패키지를 게시하는 방법에 대한 동영상 데모를 시청하세요.
Node Package Manager(npm)은 JavaScript 및 Node.js의 기본 패키지 관리자입니다. 개발자는 npm을 사용하여 코드를 공유하고 재사용하며, 종속성을 관리하고 프로젝트 워크플로우를 간소화합니다. GitLab에서 npm 패키지는 소프트웨어 개발 수명 주기에서 중요한 역할을 합니다.
npm 엔드포인트에 대한 자세한 내용은 API를 참조하세요.
GitLab 패키지 레지스트리에 npm 패키지를 게시하는 방법에 대한 동영상 데모를 시청하세요.
패키지 레지스트리 인증#
비공개 프로젝트 또는 비공개 그룹에서 패키지를 게시하거나 설치하려면 패키지 레지스트리에 인증해야 합니다. 프로젝트 또는 그룹이 공개인 경우 인증이 필요하지 않습니다. 프로젝트가 내부인 경우 GitLab 인스턴스에 등록된 사용자여야 합니다. 익명 사용자는 내부 프로젝트에서 패키지를 가져올 수 없습니다.
인증하려면 다음 중 하나를 사용할 수 있습니다:
- 범위를
api로 설정한 다음 토큰 중 하나: - 범위를
read_package_registry,write_package_registry, 또는 둘 다로 설정한 배포 토큰. - CI/CD 파이프라인으로 패키지를 게시하려는 경우 CI/CD 작업 토큰.
조직에서 이중 인증(2FA)을 사용하는 경우 범위를 api로 설정한 개인 액세스 토큰을 사용해야 합니다.
자세한 내용은 토큰 가이드를 참조하세요.
여기에 문서화된 방법 외의 인증 방법은 사용하지 마세요. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.
.npmrc 파일 사용#
package.json과 같은 디렉토리에 .npmrc 파일을 만들거나 편집합니다. .npmrc 파일에 다음 줄을 포함시킵니다:
//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"
GitLab 토큰(또는 모든 토큰)을 .npmrc 파일이나 저장소에 커밋될 수 있는 다른 파일에 직접 하드코딩하지 마세요.
예시:
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
<domain_name>을 도메인 이름으로 교체하세요. 예를 들어 gitlab.com.
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
다음을 교체해야 합니다:
<domain_name>을 도메인 이름으로. 예를 들어gitlab.com.<group_id>를 그룹 홈 페이지의 그룹 ID로.
//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"
다음을 교체해야 합니다:
<domain_name>을 도메인 이름으로. 예를 들어gitlab.com.<project_id>를 프로젝트 개요 페이지의 프로젝트 ID로.
npm config set 사용#
이를 위해:
npm config set -- //<domain_name>/:_authToken=<token>
npm 버전에 따라 URL을 변경해야 할 수 있습니다:
- npm 버전 7 이하에서는 엔드포인트의 전체 URL을 사용하세요.
- 버전 8 이상에서는
_authToken파라미터에 전체 URL 대신 URI 프래그먼트를 사용할 수 있습니다. 자세한 내용은 인증 관련 구성을 참조하세요.
Yarn Classic 1.x를 사용하는 경우 인증 토큰을 설정할 때 전체 엔드포인트 경로를 지정해야 합니다. Yarn Classic은 계층적 인증 매칭을 지원하지 않으므로 //gitlab.com/api/v4/와 같은 상위 경로에 설정된 토큰이 //gitlab.com/api/v4/groups/<group_id>/-/packages/npm/과 같은 하위 경로에 적용되지 않습니다. 항상 전체 그룹 또는 프로젝트 경로를 사용하세요. 자세한 내용은 Yarn Classic이 단축된 인증 경로로 401 Unauthorized를 반환합니다를 참조하세요.
예시:
npm config set -- //<domain_name>/api/v4/packages/npm/:_authToken=<token>
다음을 교체해야 합니다:
<domain_name>을 도메인 이름으로. 예를 들어gitlab.com.<token>을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로.
npm config set -- //<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken=<token>
다음을 교체해야 합니다:
<domain_name>을 도메인 이름으로. 예를 들어gitlab.com.<group_id>를 그룹 홈 페이지의 그룹 ID로.<token>을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로.
npm config set -- //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken=<token>
다음을 교체해야 합니다:
<domain_name>을 도메인 이름으로. 예를 들어gitlab.com.<project_id>를 프로젝트 ID로.<token>을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로.
레지스트리 URL 설정#
GitLab 패키지 레지스트리에서 패키지를 게시하거나 설치하려면 올바른 레지스트리 URL을 사용하도록 npm을 구성해야 합니다. 구성 방법과 URL 구조는 패키지를 게시하는지 설치하는지에 따라 다릅니다.
레지스트리 URL을 구성하기 전에 다양한 구성 방법의 범위를 이해하는 것이 중요합니다:
.npmrc파일: 구성이 파일이 포함된 폴더에 로컬입니다.npm config set명령: 전역 npm 구성을 수정하고 시스템에서 실행되는 모든 npm 명령에 영향을 미칩니다.package.json의publishConfig: 이 구성은 패키지에 특화되어 해당 패키지를 게시할 때만 적용됩니다.
npm config set을 실행하면 전역 npm 구성이 변경됩니다. 이 변경은 현재 작업 디렉토리와 관계없이 시스템에서 실행되는 모든 npm 명령에 영향을 미칩니다. 특히 공유 시스템에서 이 방법을 사용할 때 주의하세요.
패키지 게시#
패키지를 게시할 때는 프로젝트 엔드포인트를 사용하세요:
https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
gitlab.example.com을 GitLab 인스턴스의 도메인으로, <project_id>를 프로젝트 ID로 교체하세요.
이 URL을 구성하려면 다음 방법 중 하나를 사용하세요:
프로젝트 루트에 .npmrc 파일을 만들거나 편집하세요:
@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 명령을 사용하세요:
npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
package.json에 publishConfig 섹션을 추가하세요:
{
"publishConfig": {
"@scope:registry": "https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/"
}
}
@scope를 패키지의 범위로 교체하세요.
패키지 설치#
패키지를 설치할 때는 프로젝트, 그룹 또는 인스턴스 엔드포인트를 사용할 수 있습니다. URL 구조는 그에 따라 다릅니다. 이 URL을 구성하려면 다음 방법 중 하나를 사용하세요:
프로젝트 루트에 .npmrc 파일을 만들거나 편집하세요. 필요에 따라 적절한 URL을 사용하세요:
-
프로젝트의 경우:
@scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/ -
그룹의 경우:
@scope:registry=https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/ -
인스턴스의 경우:
@scope:registry=https://gitlab.example.com/api/v4/packages/npm/
적절한 URL과 함께 npm config set 명령을 사용하세요:
-
프로젝트의 경우:
npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/ -
그룹의 경우:
npm config set @scope:registry=https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/ -
인스턴스의 경우:
npm config set @scope:registry=https://gitlab.example.com/api/v4/packages/npm/
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에 사용되는 값은 패키지 자체의 소스 코드가 있는 프로젝트의 루트가 아닌 패키지를 호스팅하는 프로젝트의 루트입니다. 범위는 소문자여야 합니다.- 패키지 이름은 원하는 것으로 지정할 수 있습니다.
자세한 내용은 범위가 지정된 패키지를 참조하세요.
| 프로젝트 URL | 패키지 레지스트리 위치 | 범위 | 전체 패키지 이름 |
|---|---|---|---|
https://gitlab.com/my-org/engineering-group/analytics |
Analytics | @my-org |
@my-org/package-name |
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 작업 실행 중 인증을 위한 .npmrc 파일을 만들 수 있습니다.
.npmrc 파일을 생성할 때 기본 포트인 경우 ${CI_SERVER_HOST} 뒤에 포트를 지정하지 마세요.
http URL의 기본값은 80이고 https URL의 기본값은 443입니다.
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 작업이 실행될 때 패키지가 패키지 레지스트리에 게시됩니다.
패키지 설치#
여러 패키지가 같은 이름과 버전을 가지고 있는 경우 패키지를 설치할 때 가장 최근에 게시된 패키지가 검색됩니다.
GitLab 프로젝트, 그룹 또는 인스턴스에서 패키지를 설치할 수 있습니다:
- 인스턴스: 다른 GitLab 그룹이나 자체 네임스페이스에 많은 npm 패키지가 있는 경우 사용합니다.
- 그룹: 같은 GitLab 그룹의 다른 프로젝트에 많은 npm 패키지가 있는 경우 사용합니다.
- 프로젝트: npm 패키지가 적고 같은 GitLab 그룹에 없는 경우 사용합니다.
인스턴스에서 설치#
사전 요구 사항:
- 패키지가 범위가 지정된 명명 규칙에 따라 게시되었습니다.
-
패키지 레지스트리에 인증합니다.
-
레지스트리를 설정합니다:
npm config set @scope:registry https://<domain_name>.com/api/v4/packages/npm/@scope를 패키지를 설치하는 프로젝트의 최상위 그룹으로 교체합니다.<domain_name>을 도메인 이름(예:gitlab.com)으로 교체합니다.
-
패키지를 설치합니다:
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://<domain_name>/api/v4/groups/<group_id>/-/packages/npm/@scope를 패키지를 설치하는 그룹의 최상위 그룹으로 교체합니다.<domain_name>을 도메인 이름(예:gitlab.com)으로 교체합니다.<group_id>를 그룹 홈 페이지에 있는 그룹 ID로 교체합니다.
-
패키지를 설치합니다:
npm install @scope/my-package
프로젝트에서 설치#
-
패키지 레지스트리에 인증합니다.
-
레지스트리를 설정합니다:
npm config set @scope:registry=https://<domain_name>/api/v4/projects/<project_id>/packages/npm/@scope를 패키지를 설치하는 프로젝트의 최상위 그룹으로 교체합니다.<domain_name>을 도메인 이름(예:gitlab.com)으로 교체합니다.<project_id>를 프로젝트 개요 페이지에 있는 프로젝트 ID로 교체합니다.
-
패키지를 설치합니다:
npm install @scope/my-package
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 파일을 편집하거나 만드세요. 예시:
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을 구성하세요.
npmjs.com으로 패키지 전달#
히스토리
- GitLab 17.0에서 필요한 역할이 Maintainer에서 Owner로 변경되었습니다.
패키지 레지스트리에서 npm 패키지를 찾을 수 없는 경우 GitLab은 요청 클라이언트가 npmjs.com으로 요청을 재전송할 수 있도록 HTTP 리디렉션으로 응답합니다.
관리자는 지속적 통합 설정에서 이 동작을 비활성화할 수 있습니다.
그룹 소유자는 그룹 패키지 및 레지스트리 설정에서 이 동작을 비활성화할 수 있습니다.
개선 사항은 에픽 3608에서 추적됩니다.
패키지 더 이상 사용하지 않음(deprecate) 처리#
히스토리
- GitLab 16.0에서 도입되었습니다.
패키지를 더 이상 사용하지 않음으로 표시하여 패키지를 가져올 때 더 이상 사용하지 않음 경고가 표시되도록 할 수 있습니다.
사전 요구 사항:
- 패키지를 삭제하는 데 필요한 권한이 있어야 합니다.
- 패키지 레지스트리에 인증되어 있어야 합니다.
명령줄에서 다음을 실행하세요:
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 역할이 있어야 합니다.
패키지를 삭제하기 전에 관련 보안 위험을 이해해야 합니다.
패키지를 삭제하려면 다음 중 하나를 수행할 수 있습니다:
유용한 힌트#
다른 조직의 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 클라이언트에 노출합니다:
nameversionsnameversiondeprecateddependenciesdevDependenciesbundleDependenciespeerDependenciesbindirectoriesdistengines_hasShrinkwraphasInstallScript:true(이 버전에 설치 스크립트가 있는 경우)
자세한 내용은 축약된 버전 객체를 참조하세요.
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 15.10에서 도입되었습니다.
GitLab CI/CD 작업에서 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을 실행하면 두 가지 시나리오 중 하나가 발생합니다:
- 패키지 전달이 활성화된 경우(기본값), GitLab은 공개 및 비공개 패키지 모두의 취약점 정보를 검색하기 위해 감사 요청을
npmjs.com으로 전달합니다. - 패키지 전달이 비활성화된 경우, GitLab은 빈 결과 집합을 반환합니다. GitLab은 독립적으로 패키지를 취약점에 대해 스캔하지 않습니다.
중요 보안 고려 사항#
GitLab을 패키지 레지스트리로 지정하지 않으면(--registry 플래그를 사용하거나 .npmrc 파일에서 기본 레지스트리로 설정하지 않으면) 감사 요청이 대신 공개 npm 레지스트리로 이동합니다.
이 경우 요청 본문에는 비공개 GitLab 패키지를 포함한 프로젝트의 모든 패키지에 대한 정보가 포함됩니다.
비공개 패키지 정보가 GitLab 내에 유지되도록 npm audit 명령을 실행할 때 항상 GitLab 레지스트리를 지정하세요.
알려진 문제#
- 감사 결과는 패키지 전달이 활성화된 것에 따라 다릅니다. 전달이 관리자 또는 그룹 소유자에 의해 비활성화된 경우
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 오류 발생#
CI_JOB_TOKEN을 사용하여 다른 프로젝트에 종속성이 있는 npm 패키지를 설치하면 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자를 초과하지 않는지 확인하세요.
