Yarn 1 (Classic) 및 Yarn 2+로 패키지를 게시하고 설치할 수 있습니다.

배포 컨테이너에서 사용되는 Yarn 버전을 확인하려면 yarn publish를 호출하는 CI/CD 스크립트 작업 블록의 script 블록에서 yarn --version을 실행하세요. Yarn 버전은 파이프라인 출력에 표시됩니다.

패키지 레지스트리 인증#

패키지 레지스트리와 상호 작용하려면 토큰이 필요합니다. 달성하려는 목표에 따라 다른 토큰을 사용할 수 있습니다. 자세한 내용은 토큰에 대한 안내를 참조하세요.

• 조직에서 이중 인증(2FA)을 사용하는 경우 api 범위가 설정된 개인 액세스 토큰을 사용해야 합니다.
• CI/CD 파이프라인으로 패키지를 게시하는 경우 개인 러너와 함께 CI/CD Job 토큰을 사용할 수 있습니다. 인스턴스 러너의 경우 변수를 등록할 수도 있습니다.

게시를 위한 Yarn 구성#

패키지 레지스트리에 게시하도록 Yarn을 구성하려면 .yarnrc.yml 파일을 편집합니다. 이 파일은 package.json 파일과 같은 위치인 프로젝트의 루트 디렉토리에서 찾을 수 있습니다.

• .yarnrc.yml을 편집하고 다음 구성을 추가합니다:

  npmScopes:
    <my-org>:
      npmPublishRegistry: 'https://<domain>/api/v4/projects/<project_id>/packages/npm/'
      npmAlwaysAuth: true
      npmAuthToken: '<token>'
  

  이 구성에서:

  • <my-org>를 조직 범위로 교체합니다. @ 기호는 포함하지 마세요.
  • <domain>을 도메인 이름으로 교체합니다.
  • <project_id>를 프로젝트 개요 페이지에서 찾을 수 있는 프로젝트 ID로 교체합니다.
  • <token>을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 교체합니다.

Yarn Classic에서는 publishConfig["@scope:registry"]로 범위가 지정된 레지스트리가 지원되지 않습니다. 자세한 내용은 Yarn pull request 7829를 참조하세요. 대신 package.json 파일에서 publishConfig를 registry로 설정합니다.

패키지 게시#

명령줄에서 또는 GitLab CI/CD로 패키지를 게시할 수 있습니다.

명령줄 사용#

패키지를 수동으로 게시하려면:

• 다음 명령을 실행합니다:

  # Yarn 1 (Classic)
  yarn publish
  
  # Yarn 2+
  yarn npm publish
  

CI/CD 사용#

인스턴스 러너(기본) 또는 개인 러너(고급)로 패키지를 자동으로 게시할 수 있습니다. CI/CD로 게시할 때 파이프라인 변수를 사용할 수 있습니다.

패키지 설치#

인스턴스 또는 프로젝트에서 설치할 수 있습니다. 동일한 이름과 버전의 패키지가 여러 개 있는 경우 패키지를 설치할 때 가장 최근에 게시된 패키지만 검색됩니다.

범위가 지정된 패키지 이름#

인스턴스에서 설치하려면 패키지에 범위가 있는 이름이 지정되어야 합니다. .yarnrc.yml 파일과 package.json의 publishConfig 옵션에서 패키지의 범위를 설정할 수 있습니다. 프로젝트 또는 그룹에서 설치하는 경우 패키지 명명 규칙을 따를 필요가 없습니다.

패키지 범위는 @로 시작하며 @owner/package-name 형식을 따릅니다:

• @owner는 패키지 소스 코드가 있는 프로젝트의 루트가 아닌 패키지를 호스팅하는 최상위 프로젝트입니다.
• 패키지 이름은 무엇이든 될 수 있습니다.

예를 들어:

인스턴스에서 설치#

동일한 조직 범위에서 많은 패키지를 작업하는 경우 인스턴스에서 설치하는 것을 고려하세요.

1. 조직 범위를 구성합니다. .yarnrc.yml 파일에 다음을 추가합니다:

   npmScopes:
    <my-org>:
      npmRegistryServer: 'https://<domain_name>/api/v4/packages/npm'
   

   • <my-org>를 @ 기호를 제외한 패키지를 설치하는 프로젝트의 루트 레벨 그룹으로 교체합니다.
   • <domain_name>을 예를 들어 gitlab.com과 같은 도메인 이름으로 교체합니다.

2. 선택 사항. 패키지가 비공개인 경우 패키지 레지스트리에 대한 접근을 구성해야 합니다:

   npmRegistries:
     //<domain_name>/api/v4/packages/npm:
       npmAlwaysAuth: true
       npmAuthToken: '<token>'
   

   • <domain_name>을 예를 들어 gitlab.com과 같은 도메인 이름으로 교체합니다.
   • <token>을 배포 토큰(권장), 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 교체합니다.

3. Yarn으로 패키지를 설치합니다.

그룹 또는 프로젝트에서 설치#

일회성 패키지가 있는 경우 그룹 또는 프로젝트에서 설치할 수 있습니다.

Yarn으로 설치#

yarn add @scope/my-package

Yarn 패키지 삭제#

사전 요구 사항:

• Maintainer 또는 Owner 권한이 있어야 합니다.

패키지를 삭제하기 전에 관련 보안 위험을 이해하세요.

패키지를 삭제하려면 다음 중 하나를 수행할 수 있습니다:

• UI 사용.
• API 사용.

관련 항목#

• npm 패키지 레지스트리 문서
• Yarn Migration Guide
• Yarn 패키지 빌드

문제 해결#

npm 레지스트리의 패키지 레지스트리에서 Yarn 실행 오류#

npm 레지스트리와 함께 Yarn을 사용하는 경우 다음과 같은 오류 메시지가 표시될 수 있습니다:

yarn install v1.15.2
warning package.json: No license field
info No lockfile found.
warning XXX: No license field
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
error An unexpected error occurred: "https://gitlab.example.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"".
info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log".
info Visit https://classic.yarnpkg.com/en/docs/cli/install for documentation about this command

이 경우 다음 명령은 현재 디렉토리에 .yarnrc라는 파일을 만듭니다. 전역 구성을 위한 사용자 홈 디렉토리나 프로젝트별 구성을 위한 프로젝트 루트에 있는지 확인하세요:

yarn config set '//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken' '<token>'
yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' '<token>'

그룹 설치에서 tarball을 가져올 때 Yarn Classic이 404 Not Found를 반환#

Yarn Classic으로 그룹의 레지스트리에서 패키지를 설치할 때 패키지 해결은 성공하지만 tarball 다운로드가 404 Not Found 오류로 실패할 수 있습니다:

[1/4] Resolving packages...
[2/4] Fetching packages...
error Error: https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/@scope/my-package/-/@scope/my-package-1.0.0.tgz: Request failed "404 Not Found"

이 오류는 그룹 레지스트리가 반환하는 패키지 메타데이터에 프로젝트 엔드포인트를 가리키는 tarball 다운로드 URL이 포함되어 있기 때문에 발생합니다. .npmrc 파일에 그룹 엔드포인트에 대한 인증 토큰만 있는 경우 프로젝트 엔드포인트에 대한 요청은 인증되지 않아 404를 반환합니다.

이 이슈를 해결하려면 .npmrc 파일에 그룹과 프로젝트 엔드포인트 모두에 대한 인증 토큰을 추가하세요:

# .npmrc
//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이 401 Unauthorized를 반환#

GitLab 패키지 레지스트리와 함께 Yarn Classic을 사용할 때 인증 토큰이 유효함에도 401 Unauthorized 오류가 발생할 수 있습니다. 오류 메시지는 다음과 같이 나타날 수 있습니다:

error Couldn't find package "@scope/my-package" on the "npm" registry.

--verbose 플래그를 사용하면 로그에 401 상태 코드가 표시됩니다:

verbose Performing "GET" request to "https://gitlab.com/api/v4/groups/<group_id>/-/packages/npm/..."
verbose Request "https://gitlab.com/api/v4/groups/<group_id>/-/packages/npm/..." finished with status code 401.

이 이슈는 .npmrc의 _authToken 항목이 전체 엔드포인트 경로 대신 단축된 상위 경로를 사용할 때 발생합니다. 예를 들어:

# Does NOT work with Yarn Classic
//gitlab.com/api/v4/:_authToken='<token>'

npm 버전 8 이상은 계층적 인증 매칭을 지원하지만(상위 경로에 설정된 토큰이 모든 하위 경로에 적용), Yarn Classic은 _authToken 항목과 레지스트리 URL 사이의 정확한 경로 일치가 필요합니다.

이 이슈를 해결하려면 .npmrc 파일에서 인증하는 각 레지스트리에 대해 전체 엔드포인트 경로를 사용하세요. 예를 들어, 특정 프로젝트에 호스팅된 패키지가 있는 그룹 레지스트리에서 설치하는 경우:

# .npmrc
//gitlab.com/api/v4/groups/<group_id>/-/packages/npm/:_authToken='<token>'
//gitlab.com/api/v4/projects/<project_id>/packages/npm/:_authToken='<token>'

그룹 엔드포인트가 반환하는 패키지 메타데이터에 프로젝트 엔드포인트를 가리키는 tarball 다운로드 URL이 포함되어 있으므로 프로젝트 항목이 필요합니다.

yarn install이 종속성으로 리포지터리를 클론하는 데 실패#

Dockerfile에서 yarn install을 사용하는 경우 Dockerfile을 빌드할 때 다음과 같은 오류가 발생할 수 있습니다:

...
#6 8.621 fatal: unable to access 'https://gitlab.com/path/to/project/': Problem with the SSL CA cert (path? access rights?)
#6 8.621 info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.
#6 ...

이 이슈를 해결하려면 .dockerignore 파일의 모든 Yarn 관련 경로에 느낌표(!)를 추가하세요.

**

!./package.json
!./yarn.lock
...