GitLab 패키지 레지스트리를 사용하여 semantic-release를 활용해 npm 패키지 게시하기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

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

전체 예제 소스를 보거나 복제할 수도 있습니다.

모듈 초기화

  1. 터미널을 열고 프로젝트 리포지터리로 이동합니다.

  2. npm init을 실행합니다. 프로젝트 경로가 gitlab-examples/semantic-release-npm인 경우 모듈의 이름을 @gitlab-examples/semantic-release-npm으로 지정합니다.

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

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

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

    {
  "scripts": {
    "semantic-release": "semantic-release"
  },
  "publishConfig": {
    "access": "public"
  },
  "files": [ <파일 경로 여기에 입력> ]
}

  5. files 키를 수정하여 게시된 모듈에 포함해야 하는 모든 파일을 선택하는 glob 패턴을 추가합니다. files에 대한 자세한 내용은 npm 문서에서 찾을 수 있습니다.

  6. 프로젝트에 .gitignore 파일을 추가하여 node_modules를 커밋하지 않도록 합니다: 

    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는 publish 작업 중에 패키지 레지스트리에 인증하는 데 사용되는 임시 .npmrc를 생성합니다.

CI/CD 변수 설정

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

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. 설정 > 액세스 토큰을 선택합니다.
  3. 토큰 이름 상자에 토큰 이름을 입력합니다.
  4. 스코프 선택에서 api 확인란을 선택합니다.
  5. 프로젝트 액세스 토큰 생성을 선택합니다.
  6. 값을 복사합니다.
  7. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
  8. 설정 > CI/CD를 선택합니다.
  9. 변수를 확장합니다.
  10. 변수 추가를 선택합니다.
  11. Key 상자에 GITLAB_TOKEN을 입력합니다.
  12. Value 상자에 토큰을 붙여넣기합니다.
  13. Mask variable 확인란을 선택합니다.
  14. 변수 추가를 선택합니다.

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와 같은 메시지로 커밋을 생성하여 파이프라인을 테스트합니다.

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

작은 업데이트를 게시하려면 다음과 같이 커밋 메시지를 사용합니다: 

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가 주 리포지터리에서 태그를 재생성합니다.

이러한 동작을 피하려면 다음 중 하나를 수행할 수 있습니다: