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

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

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

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

Yarn 설명서를 사용하여 Yarn Classic 및 Yarn 2+를 시작할 수 있습니다.

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

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

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

패키지를 게시하려면 토큰이 필요합니다. 달성하려는 목표에 따라 다양한 토큰을 사용할 수 있습니다. 자세한 정보는 토큰에 관한 지침을 확인하세요.

  • 조직에서 이중 인증(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>을 배포 토큰, 그룹 엑세스 토큰, 프로젝트 엑세스 토큰 또는 개인 엑세스 토큰으로 바꾸세요.

Yarn Classic에서는 package.json 파일에서 스코프 레지스트리가 작동하지 않으며, Yarn Classic의 경우 publishConfig 아래에 @scope:registry 대신 registry가 있어야 합니다. GitLab 패키지 레지스트리로 패키지를 게시할 수 있습니다.

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

# 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
값 <단계-3에서-생성된-토큰>
유형 변수
보호된 변수 선택됨
마스크 변수 선택됨
변수 확장 선택됨

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

  1. Yarn 패키지 소스 코드가 포함된 저장소로 이동합니다.
  2. 왼쪽 사이드바에서 설정 > 저장소를 선택합니다.
    • 태그가 있는 브랜치에서 빌드하는 경우 보호된 태그를 선택하고 의미 있는 버전을 위해 v* (와일드카드)을 추가합니다.
    • 태그가 없는 브랜치에서 빌드하는 경우 보호된 브랜치를 선택합니다.

그런 다음 위에서 생성한 NPM_AUTH_TOKEN을 패키지 프로젝트 루트 디렉터리에 있는 .yarnrc.yml 구성에 추가하거나 만드세요: 

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

이 구성에서 <my-org>를 조직 스코프로 바꾸세요. @ 기호는 제외합니다.

프라이빗 러너

CI_JOB_TOKEN을 패키지 프로젝트 루트 디렉터리에 있는 .yarnrc.yml 구성에 추가하세요. 

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> Package Name Example @my-org @my-org/package-name
https://gitlab.com/<example-org>/<group-name>/<project-name> Project Name @example-org @example-org/project-name

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

.yarnrc.yml의 구성은 패키지를 사용하는 프로젝트 루트에 추가하거나 시스템 사용자 홈 디렉토리에 글로벌 구성을 사용할 수 있습니다.

인스턴스 수준에서 설치

.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 Classic의 경우

Yarn Classic 설정에는 .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 registry를 사용하여 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/<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: 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
...