InfoGrab Docs

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

요약

이 가이드는 semantic-release를 사용하여 GitLab 패키지 레지스트리에 npm 패키지를 자동으로 게시하는 방법을 보여줍니다. 완전한 예시 소스를 보거나 포크할 수도 있습니다. 터미널을 열고 프로젝트 리포지터리로 이동합니다.

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

완전한 예시 소스를 보거나 포크할 수도 있습니다.

모듈 초기화#

  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": [ <path(s) to files here> ]
}

  5. 게시된 모듈에 포함해야 하는 모든 파일을 선택하는 glob 패턴으로 files 키를 업데이트합니다. files에 대한 자세한 내용은 npm 문서에서 확인할 수 있습니다.

  6. 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를 실행하는 단일 job publish로 파이프라인을 구성합니다. semantic-release 라이브러리는 npm 패키지의 새 버전을 게시하고 (필요한 경우) 새 GitLab 릴리스를 만듭니다.

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

CI/CD 변수 설정#

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

  1. 왼쪽 사이드바를 엽니다.
  2. 설정 > 액세스 토큰을 선택합니다.
  3. 프로젝트에서 새 토큰 추가를 선택합니다.
  4. 토큰 이름 상자에 토큰 이름을 입력합니다.
  5. 범위 선택 아래에서 api 체크박스를 선택합니다.
  6. 프로젝트 액세스 토큰 만들기를 선택합니다.
  7. 토큰 값을 복사합니다.
  8. 왼쪽 사이드바에서 설정 > CI/CD를 선택합니다.
  9. 변수를 펼칩니다.
  10. 변수 추가를 선택합니다.
  11. 가시성 아래에서 마스크됨을 선택합니다.
  12. 키 상자에 GITLAB_TOKEN을 입력합니다.
  13. 값 상자에 토큰 값을 입력합니다.
  14. 변수 추가를 선택합니다.

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

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

마이너 릴리스를 만들려면 다음과 같은 커밋 메시지를 사용합니다:

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에 의해 다시 만들어지는 경우가 있습니다. job이 태그가 여전히 있는 캐시된 리포지터리가 있는 러너에서 실행되면 semantic-release는 메인 리포지터리에서 태그를 다시 만듭니다.

이 동작을 방지하려면:

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

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
원문 보기
요약

이 가이드는 semantic-release를 사용하여 GitLab 패키지 레지스트리에 npm 패키지를 자동으로 게시하는 방법을 보여줍니다. 완전한 예시 소스를 보거나 포크할 수도 있습니다. 터미널을 열고 프로젝트 리포지터리로 이동합니다.

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

완전한 예시 소스를 보거나 포크할 수도 있습니다.

모듈 초기화#

  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": [ <path(s) to files here> ]
}

  5. 게시된 모듈에 포함해야 하는 모든 파일을 선택하는 glob 패턴으로 files 키를 업데이트합니다. files에 대한 자세한 내용은 npm 문서에서 확인할 수 있습니다.

  6. 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를 실행하는 단일 job publish로 파이프라인을 구성합니다. semantic-release 라이브러리는 npm 패키지의 새 버전을 게시하고 (필요한 경우) 새 GitLab 릴리스를 만듭니다.

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

CI/CD 변수 설정#

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

  1. 왼쪽 사이드바를 엽니다.
  2. 설정 > 액세스 토큰을 선택합니다.
  3. 프로젝트에서 새 토큰 추가를 선택합니다.
  4. 토큰 이름 상자에 토큰 이름을 입력합니다.
  5. 범위 선택 아래에서 api 체크박스를 선택합니다.
  6. 프로젝트 액세스 토큰 만들기를 선택합니다.
  7. 토큰 값을 복사합니다.
  8. 왼쪽 사이드바에서 설정 > CI/CD를 선택합니다.
  9. 변수를 펼칩니다.
  10. 변수 추가를 선택합니다.
  11. 가시성 아래에서 마스크됨을 선택합니다.
  12. 키 상자에 GITLAB_TOKEN을 입력합니다.
  13. 값 상자에 토큰 값을 입력합니다.
  14. 변수 추가를 선택합니다.

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

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

마이너 릴리스를 만들려면 다음과 같은 커밋 메시지를 사용합니다:

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에 의해 다시 만들어지는 경우가 있습니다. job이 태그가 여전히 있는 캐시된 리포지터리가 있는 러너에서 실행되면 semantic-release는 메인 리포지터리에서 태그를 다시 만듭니다.

이 동작을 방지하려면: