GitLab 패키지 레지스트리에 npm 패키지 게시하기 (semantic-release 사용)

Tier: Free, Premium, Ultimate

Offering: GitLab.com, Self-managed, GitLab Dedicated

이 가이드는 semantic-release를 사용하여 npm 패키지를 GitLab 패키지 레지스트리로 자동으로 게시하는 방법을 보여줍니다.

전체 예제 소스를 볼 수도 있거나 포크할 수 있습니다.

모듈 초기화

터미널을 열고 프로젝트의 리포지토리로 이동합니다.
npm init을 실행합니다. 패키지 레지스트리의 명명 규칙에 따라 모듈의 이름을 지정합니다 naming conventions. 예를 들어, 프로젝트 경로가 gitlab-examples/semantic-release-npm이면 모듈 이름은 @gitlab-examples/semantic-release-npm으로 지정합니다.

다음 npm 패키지를 설치합니다:

npm install semantic-release @semantic-release/git @semantic-release/gitlab @semantic-release/npm --save-dev

모듈의 package.json에 다음 속성을 추가합니다:

{
  "scripts": {
    "semantic-release": "semantic-release"
  },
  "publishConfig": {
    "access": "public"
  },
  "files": [ <path(s) to files here> ]
}

게시할 모듈에 포함해야 하는 모든 파일을 선택하는 glob 패턴으로 files 키를 업데이트합니다. files에 대한 자세한 내용은 npm 문서에서 확인할 수 있습니다.
node_modules를 커밋하지 않도록 프로젝트에 .gitignore 파일을 추가합니다:
```
node_modules
```

파이프라인 구성

다음 내용을 가진 .gitlab-ci.yml을 생성합니다:

default:
  image: node:latest
  before_script:
    - npm ci --cache .npm --prefer-offline
    - |
      {
        echo "@${CI_PROJECT_ROOT_NAMESPACE}:registry=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
        echo "${CI_API_V4_URL#https?}/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=\${CI_JOB_TOKEN}"
      } | tee -a .npmrc
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - .npm/

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

variables:
  NPM_TOKEN: ${CI_JOB_TOKEN}

stages:
  - release

publish:
  stage: release
  script:
    - npm run semantic-release
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

이 예제는 semantic-release를 실행하는 단일 작업 publish로 파이프라인을 구성합니다. semantic-release 라이브러리는 npm 패키지의 새 버전을 게시하고 필요할 경우 새로운 GitLab 릴리스를 생성합니다.

기본 before_script는 게시 작업 중에 패키지 레지스트리에 인증하는 데 사용되는 임시 .npmrc를 생성합니다.

CI/CD 변수 설정

패키지를 게시하는 과정의 일환으로, semantic-release는 package.json의 버전 번호를 증가시킵니다. 이 변경 사항을 커밋하고 GitLab로 푸시하기 위해 파이프라인에는 GITLAB_TOKEN이라는 사용자 지정 CI/CD 변수가 필요합니다. 이 변수를 생성하려면:

왼쪽 사이드바에서 아바타를 선택합니다.
Preferences > Access tokens를 선택합니다.
Token name 상자에 토큰 이름을 입력합니다.
select scopes 아래에서 api 체크박스를 선택합니다.
Create project access token을 선택합니다.
값을 복사합니다.
왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > CI/CD를 선택합니다.
Variables를 확장합니다.
Add variable을 선택합니다.
Key 상자에 GITLAB_TOKEN을 입력합니다.
Value 상자에 토큰을 붙여넣습니다.
Mask variable 체크박스를 선택합니다.
Add variable을 선택합니다.

semantic-release 구성하기

semantic-release는 프로젝트의 .releaserc.json 파일에서 구성 정보를 가져옵니다. 저장소의 루트에 .releaserc.json 파일을 생성하세요:

{
  "branches": ["master"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/gitlab",
    "@semantic-release/npm",
    [
      "@semantic-release/git",
      {
        "assets": ["package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

릴리스를 게시하기 시작하기

다음과 같은 메시지를 포함한 커밋을 생성하여 파이프라인을 테스트하세요:

fix: testing patch releases

기본 브랜치에 커밋을 푸시합니다. 그러면 파이프라인이 프로젝트의 Releases 페이지에서 새 릴리스(v1.0.0)를 생성하고, 프로젝트의 Package Registry 페이지에 패키지의 새 버전을 게시해야 합니다.

마이너 릴리스를 생성하려면 다음과 같은 커밋 메시지를 사용하세요:

feat: testing minor releases

또는, 비호환 변경 사항을 위해:

feat: testing major releases

BREAKING CHANGE: This is a breaking change.

커밋 메시지가 릴리스에 어떻게 매핑되는지에 대한 자세한 정보는 semantic-releases의 문서에서 확인할 수 있습니다.

프로젝트에서 모듈 사용하기

게시된 모듈을 사용하려면, 해당 모듈에 의존하는 프로젝트에 .npmrc 파일을 추가하세요. 예를 들어, 예제 프로젝트의 모듈을 사용하려면:

@gitlab-examples:registry=https://gitlab.com/api/v4/packages/npm/

그런 다음 모듈을 설치하세요:

npm install --save @gitlab-examples/semantic-release-npm

문제 해결

삭제된 Git 태그가 다시 나타남

저장소에서 삭제된 Git 태그는 GitLab 러너가 캐시된 저장소 버전을 사용할 때 semantic-release에 의해 다시 생성될 수 있습니다. 태그가 여전히 있는 캐시된 저장소에서 러너가 작업을 실행하면 semantic-release는 메인 저장소에 태그를 재생성합니다.

이 동작을 피하려면 다음 중 하나를 선택할 수 있습니다:

GIT_STRATEGY: clone로 러너를 구성합니다.
CI/CD 스크립트에 git fetch --prune-tags 명령을 포함합니다.

GitLab 패키지 레지스트리에 npm 패키지 게시하기 (semantic-release 사용)

모듈 초기화

파이프라인 구성

CI/CD 변수 설정

semantic-release 구성하기

릴리스를 게시하기 시작하기

프로젝트에서 모듈 사용하기

문제 해결

삭제된 Git 태그가 다시 나타남

도움말

기능 사용 가능성과 제품 평가판

도움받기