Yarn을 사용하여 패키지 게시하기

Yarn 1 (Classic) 및 Yarn 2+를 사용하여 패키지를 게시할 수 있습니다.

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

Yarn 패키지를 빌드하는 방법을 알아보세요.

시작하려면 Yarn 문서를 참조하세요.

Yarn Classic 및

Yarn 2+.

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

Yarn을 사용하여 GitLab 패키지 레지스트리에 게시할 수 있습니다.

패키지 레지스트리에 대한 인증

패키지를 게시하려면 토큰이 필요합니다. 달성하려는 목표에 따라 다양한 토큰이 제공됩니다. 자세한 내용은 토큰에 대한 안내를 검토하세요.

  • 귀하의 조직이 2단계 인증(2FA)을 사용하는 경우, api 범위가 설정된 개인 액세스 토큰을 사용해야 합니다.

  • CI/CD 파이프라인을 통해 패키지를 게시하는 경우, 개인 실행기에서 CI 작업 토큰을 사용하거나 인스턴스 러너를 위한 변수를 등록할 수 있습니다.

게시 구성

게시하려면 .yarnrc.yml에 다음 구성을 설정하십시오. 이 파일은 package.json이 있는 패키지 프로젝트 소스의 루트 디렉토리에 위치해야 합니다.

npmScopes:
  <my-org>:
    npmPublishRegistry: 'https://<your_domain>/api/v4/projects/<your_project_id>/packages/npm/'
    npmAlwaysAuth: true
    npmAuthToken: '<your_token>'

이 구성에서:

  • <my-org>를 @ 기호를 제외한 조직 범위로 바꾸십시오.

  • <your_domain>을 귀하의 도메인 이름으로 바꾸십시오.

  • <your_project_id>를 프로젝트 개요 페이지에서 찾을 수 있는 프로젝트 ID로 바꾸십시오.

  • <your_token>을 배포 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰 또는 개인 액세스 토큰으로 바꾸십시오.

Scoped registry는 문제에 따라 Yarn Classic의 package.json 파일에서 작동하지 않습니다. 따라서 Yarn Classic의 경우 publishConfig 아래에 @scope:registry가 아닌 registry가 있어야 합니다.

GitLab 패키지 레지스트리에 명령줄이나 CI/CD 파이프라인을 사용하여 게시할 수 있습니다.

명령줄을 통한 게시 - 수동 게시 

# Yarn 1 (Classic)
yarn publish

# Yarn 2+
yarn npm publish

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

CI/CD 파이프라인을 통한 게시 - 자동 게시

이 방법을 사용할 때 파이프라인 변수를 사용할 수 있습니다.

인스턴스 러너 (기본값) 또는 개인 러너 (고급)를 사용할 수 있습니다.

인스턴스 러너

프로젝트 또는 그룹에 대한 인증 토큰을 생성하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.

  2. 왼쪽 사이드바에서 설정 > 리포지토리 > 배포 토큰을 선택합니다.

  3. read_package_registry 및 write_package_registry 범위를 가진 배포 토큰을 생성하고 생성된 토큰을 복사합니다.

  4. 왼쪽 사이드바에서 설정 > CI/CD > 변수를 선택합니다.

  5. 변수 추가를 선택하고 다음 설정을 사용합니다:

필드 값
키 NPM_AUTH_TOKEN
값 <DEPLOY-TOKEN-FROM-STEP-3>
유형 변수
보호된 변수 체크됨
마스크된 변수 체크됨
확장 변수 체크됨

보호된 변수를 사용하려면:

  1. Yarn 패키지 소스 코드가 포함된 리포지토리로 이동합니다.

  2. 왼쪽 사이드바에서 설정 > 리포지토리를 선택합니다.

    • 태그가 있는 브랜치에서 빌드하는 경우, 보호된 태그를 선택하고 v* (와일드카드)를 추가하여 의미 버전 관리를 설정합니다.

    • 태그가 없는 브랜치에서 빌드하는 경우, 보호된 브랜치를 선택합니다.

그런 다음 위에서 생성한 NPM_AUTH_TOKEN을 package.json이 있는 패키지 프로젝트 루트 디렉토리의 .yarnrc.yml 구성에 추가합니다:

npmScopes:
  <my-org>:
    npmPublishRegistry: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
    npmAlwaysAuth: true
    npmAuthToken: "${NPM_AUTH_TOKEN}"

이 구성에서 <my-org>를 @ 기호를 제외한 조직 범위로 바꾸십시오.

개인 러너

package.json 파일이 있는 패키지 프로젝트의 루트 디렉터리에서 .yarnrc.yml 구성에 CI_JOB_TOKEN을 추가하세요:

npmScopes:
  <my-org>:
    npmPublishRegistry: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
    npmAlwaysAuth: true
    npmAuthToken: "${CI_JOB_TOKEN}"

이 구성에서 <my-org>를 @ 기호를 제외한 조직 범위로 교체하세요.

CI/CD 파이프라인을 사용하여 패키지를 게시하려면, .yarnrc.yml을 포함하는 GitLab 프로젝트에서 .gitlab-ci.yml 파일을 편집하거나 생성하세요. 예를 들어 태그 푸시 시에만 트리거되도록 설정할 수 있습니다:

# Yarn 1
image: node:lts

stages:
  - deploy

rules:
- if: $CI_COMMIT_TAG

deploy:
  stage: deploy
  script:
    - yarn publish

# Yarn 2+
image: node:lts

stages:
  - deploy

rules:
  - if: $CI_COMMIT_TAG

deploy:
  stage: deploy
  before_script:
    - corepack enable
    - yarn set version stable
  script:
    - yarn npm publish

이제 파이프라인이 실행될 때 패키지가 패키지 레지스트리에 게시되어야 합니다.

패키지 설치

참고: 동일한 이름과 버전을 가진 여러 패키지가 있는 경우, 패키지를 설치할 때 가장 최근에 게시된 패키지가 검색됩니다.

패키지를 설치하려면 두 개의 API 엔드포인트 중 하나를 사용할 수 있습니다:

  • 인스턴스 수준: 조직 범위 내에서 여러 패키지를 작업할 때 가장 잘 사용됩니다.

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

  • @scope에 사용되는 값은 패키지를 호스팅하는 조직 루트 (상위 프로젝트) ...com/my-org (@my-org)이며, 패키지의 소스 코드가 있는 프로젝트의 루트는 아닙니다.
  • 범위는 항상 소문자입니다.

  • 패키지 이름은 @my-org/any-name처럼 원하는 대로 설정할 수 있습니다.

  • 프로젝트 수준: 일회성 패키지를 위한 것입니다.

프로젝트 수준에서 패키지를 설치할 계획이라면,
이름 지정 규칙을 따를 필요가 없습니다.

프로젝트 URL 패키지 레지스트리 조직 범위 전체 패키지 이름
https://gitlab.com/<my-org>/<group-name>/<package-name-example> 패키지 이름 예시 @my-org @my-org/package-name
https://gitlab.com/<example-org>/<group-name>/<project-name> 프로젝트 이름 @example-org @example-org/project-name

인스턴스 수준 또는 프로젝트 수준에서 설치할 수 있습니다.

.yarnrc.yml 구성은 package.json이 위치한 각 패키지 소비 프로젝트 루트에 추가할 수 있으며,
시스템 사용자 홈 디렉터리에 있는 전역 구성도 사용할 수 있습니다.

인스턴스 수준에서 설치

.yarnrc.yml 파일에서 전역 구성을 위한 단계는 다음과 같습니다:

  1. 조직 범위 구성.
  2. 레지스트리 설정.

조직 범위 구성 

npmScopes:
 <my-org>:
   npmRegistryServer: "https://<your_domain_name>/api/v4/packages/npm"
  • <my-org>를 패키지를 설치하는 프로젝트의 최상위 그룹으로 교체하고 @ 기호는 제외합니다.
  • <your_domain_name>를 도메인 이름으로 교체합니다. 예: gitlab.com.

레지스트리 설정

패키지가 공개된 것이 아니라면 이 단계를 건너뜁니다.

  npmRegistries:
    //<your_domain_name>/api/v4/packages/npm:
      npmAlwaysAuth: true
      npmAuthToken: "<your_token>"
  • <your_domain_name>를 도메인 이름으로 교체합니다. 예: gitlab.com.
  • <your_token>을 배포 토큰(추천), 그룹 액세스 토큰, 프로젝트 액세스 토큰, 또는 개인 액세스 토큰으로 교체합니다.

프로젝트 수준에서 설치

.yarnrc.yml 파일에서 각 프로젝트에 대해 다음 단계를 사용하세요:

  1. 프로젝트 범위 구성.
  2. 레지스트리 설정.

프로젝트 범위 구성 

npmScopes:
  <my-org>:
    npmRegistryServer: "https://<your_domain_name>/api/v4/projects/<your_project_id>/packages/npm"
  • <my-org>를 패키지를 설치하는 프로젝트의 최상위 그룹으로 교체하고 @ 기호는 제외합니다.
  • <your_domain_name>를 도메인 이름으로 교체합니다. 예: gitlab.com.
  • <your_project_id>를 프로젝트 개요 페이지에서 찾은 프로젝트 ID로 교체합니다.

레지스트리 설정 (프로젝트 수준)

패키지가 공개된 것이 아니라면 이 단계를 건너뜁니다.

npmRegistries:
  //<your_domain_name>/api/v4/projects/<your_project_id>/packages/npm:
    npmAlwaysAuth: true
    npmAuthToken: "<your_token>"
  • <your_domain_name>를 도메인 이름으로 교체합니다. 예: gitlab.com.
  • <your_token>을 배포 토큰(추천), 그룹 액세스 토큰, 프로젝트 액세스 토큰, 또는 개인 액세스 토큰으로 교체합니다.
  • <your_project_id>를 프로젝트 개요 페이지에서 찾은 프로젝트 ID로 교체합니다.

패키지 설치

Yarn 2+에서는 명령줄이나 CI/CD 파이프라인에서 yarn add를 사용하여 패키지를 설치합니다:

yarn add @scope/my-package

Yarn 클래식의 경우

Yarn 클래식 설정은 .npmrc와 .yarnrc 파일 모두가 필요합니다.

문제에서 언급됨:

  • 자격 증명을 .npmrc 파일에 배치합니다.
  • 범위 지정 레지스트리를 .yarnrc 파일에 배치합니다.
# .npmrc
//<your_domain_name>/api/v4/projects/<your_project_id>/packages/npm/:_authToken="<your_token>"

# .yarnrc
"@scope:registry" "https://<your_domain_name>/api/v4/projects/<your_project_id>/packages/npm/"

그런 다음 yarn add를 사용하여 패키지를 설치할 수 있습니다.

관련 주제

문제 해결

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] 🔍  패키지 확인 중...
[2/4] 🚚  패키지 가져오는 중...
error 예기치 않은 오류가 발생했습니다: "https://gitlab.example.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: 요청 실패 "404 Not Found"".
info 이 문제가 버그라고 생각되면 "/Users/XXX/gitlab-migration/module-util/yarn-error.log"에 제공된 정보를 포함하여 버그 보고서를 제출하세요.
info 이 명령어에 대한 문서는 https://classic.yarnpkg.com/en/docs/cli/install를 방문하세요.

이 경우, 다음 명령어는 현재 디렉토리에 .yarnrc라는 파일을 생성합니다. 전역 구성의 경우 사용자 홈 디렉토리에 있거나 프로젝트별 구성의 경우 프로젝트 루트에 있어야 합니다:

yarn config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>"
yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>"

yarn install이 종속성으로 저장소를 복제하지 못함

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

...
#6 8.621 fatal: 'https://gitlab.com/path/to/project/'에 접근할 수 없습니다: SSL CA 인증서 문제 (경로? 접근 권한?)
#6 8.621 info 이 명령어에 대한 문서는 https://yarnpkg.com/en/docs/cli/install을 방문하세요.
#6 ...

이 문제를 해결하려면 .dockerignore 파일의 모든 Yarn 관련 경로 앞에 느낌표(!)를 추가합니다.

**

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