semantic-release로 npm 패키지를 GitLab 패키지 레지스트리에 게시하기

이 가이드는 semantic-release를 이용해 npm 패키지를 GitLab 패키지 레지스트리에 자동으로 게시하는 방법을 보여줘요. 완성된 예제 소스를 보거나 포크해서 사용할 수도 있어요.

출처: 문서

본문

모듈 초기화하기

터미널을 열고 프로젝트의 저장소로 이동해요.
npm init을 실행해요. 패키지 레지스트리의 명명 규칙에 따라 모듈 이름을 정해요. 예를 들어 프로젝트 경로가 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:
    - |
      {
        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
    - npm ci --cache .npm --prefer-offline
  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

이 예제는 publish라는 하나의 잡으로 파이프라인을 구성하고, 이 잡이 semantic-release를 실행해요. semantic-release 라이브러리는 npm 패키지의 새 버전을 게시하고 (필요하다면) 새 GitLab 릴리스를 만들어요.

기본 before_script는 임시 .npmrc를 생성해서 publish 잡 중에 패키지 레지스트리에 인증하는 데 사용해요.

CI/CD 변수 설정하기

패키지 게시의 일부로, semantic-release는 package.json의 버전 번호를 올려요. semantic-release가 이 변경 사항을 커밋해서 GitLab으로 다시 푸시하려면, 파이프라인에 GITLAB_TOKEN이라는 커스텀 CI/CD 변수가 필요해요. 이 변수를 만들려면:

왼쪽 사이드바를 열어요.
Settings > Access tokens 를 선택해요.
프로젝트에서 Add new token을 선택해요.
Token name 상자에 토큰 이름을 입력해요.
Select scopes 아래에서 api 체크박스를 선택해요.
Create project access token을 선택해요.
토큰 값을 복사해요.
왼쪽 사이드바에서 Settings > CI/CD를 선택해요.
Variables를 펼쳐요.
Add variable을 선택해요.
Visibility에서 Masked를 선택해요.
Key 상자에 GITLAB_TOKEN을 입력해요.
Value 상자에 토큰 값을 입력해요.
Add variable을 선택해요.

semantic-release 구성하기

semantic-release는 프로젝트의 .releaserc.json 파일에서 구성 정보를 가져와요. 저장소 루트에 .releaserc.json을 만들어요.

{
  "branches": ["main"],
  "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}"
      }
    ]
  ]
}

위의 semantic-release 구성 예제에서 브랜치 이름을 프로젝트의 기본 브랜치로 바꿀 수 있어요.

릴리스 게시 시작하기

다음과 같은 커밋 메시지로 커밋을 만들어 파이프라인을 테스트해 보세요.

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-release 문서에서 확인할 수 있어요.

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

게시된 모듈을 사용하려면, 그 모듈에 의존하는 프로젝트에 .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/runners/configure_runners/#git-strategy)으로 구성하기.
CI/CD 스크립트에 git fetch --prune-tags 명령을 포함하기.

더 알아보기

semantic-release가 커밋 규칙(conventional commits)을 기반으로 버전을 자동 결정하는 방식은 semantic-release 문서에서 더 자세히 볼 수 있어요. GitLab 패키지 레지스트리의 다른 패키지 형식 지원이 궁금하다면 패키지 레지스트리 문서를 함께 읽어보는 걸 추천해요.