NPM 패키지 생성 및 semantic-release를 활용한 자동 배포

개요

NPM 패키지를 생성하고, semantic-release를 사용하여 GitHub Actions를 통해 자동으로 배포하는 과정을 정리합니다.

1. 프로젝트 초기화

먼저, NPM 패키지를 위한 프로젝트를 생성하고 초기화합니다.

mkdir my-npm-package && cd my-npm-package
npm init -y

이제 package.json 파일이 생성됩니다.

2. GitHub 저장소 연결

GitHub에 새로운 저장소를 생성한 후, 로컬 프로젝트를 연결합니다.

git init
git remote add origin https://github.com/your-username/my-npm-package.git
git branch -M main
git add .
git commit -m "chore: initial commit"
git push -u origin main

3. TypeScript 및 기본 설정 추가 (선택 사항)

TypeScript를 사용할 경우, 다음 명령어로 설정합니다.

npm install --save-dev typescript @types/node
npx tsc --init

tsconfig.json 파일이 생성되며, 필요에 따라 수정할 수 있습니다.

4. Lint 및 기타 도구 설정 (선택 사항)

ESLint와 Prettier를 설정하면 코드 품질을 유지하는 데 유용합니다.

npm install --save-dev eslint prettier
npx eslint --init

5. semantic-release 및 관련 패키지 설치

자동 버전 관리 및 배포를 위해 semantic-release를 설치합니다.

npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/github @semantic-release/npm

6. release.config.js 설정

프로젝트 루트에 release.config.js 파일을 생성하고 다음과 같이 설정합니다.

module.exports = {
  branches: ["main"],
  plugins: [
    "@semantic-release/commit-analyzer", // 커밋 메시지를 분석하여 버전 업데이트 유형 결정
    "@semantic-release/release-notes-generator", // 변경 사항을 기반으로 릴리스 노트 생성
    "@semantic-release/changelog", // CHANGELOG.md 파일을 자동 업데이트
    "@semantic-release/npm", // NPM 패키지 버전 업데이트 및 배포
    ["@semantic-release/git", {
      "assets": ["package.json", "CHANGELOG.md"], // 변경된 파일을 커밋
      "message": "chore(release): ${nextRelease.version} [skip ci]"
    }],
    "@semantic-release/github" // GitHub 릴리스 생성 및 태그 추가
  ]
};

.releaserc.json vs release.config.js

• .releaserc.json은 JSON 형식으로 설정을 정의하는 방식입니다.
• release.config.js는 JavaScript 파일로 설정을 정의할 수 있어 더 유연하게 구성할 수 있습니다 (예: 조건문 사용 가능).

7. GitHub Actions Workflow 추가

.github/workflows/release.yml 파일을 생성하고 아래 내용을 추가합니다.

name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "20"
      - run: npm ci
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Github action 진행시 node vesion 문제

Run npx semantic-release
[semantic-release]: node version >=20.8.1 is required. Found v18.20.7.

See https://github.com/semantic-release/semantic-release/blob/master/docs/support/node-version.md for more details and solutions.
Error: Process completed with exit code 1.

.github/workflows/release.yml에 node-version을 수정

	...
	with:
    node-version: 20.8.1
    registry-url: "https://registry.npmjs.org/"
    ...

8. GitHub Secrets 설정

GitHub 저장소의 Settings > Secrets and variables > Actions > Repository secrets에서 다음과 같이 설정합니다.

• NPM_TOKEN: NPM Access Token (NPM 계정에서 생성 가능)
• GH_TOKEN: Github의 PAT Token (Github > Settings > Developer Settings > Personal access tokens)

GitHub Actions 실행 시 permission 오류 발생 시

Settings > Actions > General > Workflow permissions에서 Read and write permissions를 체크해야 합니다.

9. 커밋 메시지 규칙 및 버전 증가 방식

semantic-release는 Conventional Commits 형식을 따릅니다.

예제:

git commit -m "feat: 새로운 기능 추가"
git commit -m "fix: 버그 수정"
git commit -m "chore: 빌드 및 설정 변경"

이 형식을 따르면 자동으로 버전이 증가합니다.

버전 증가 방식 예제 (현재 버전이 1.0.0일 때)

• feat: 새로운 기능 추가 → 1.1.0 (Minor 버전 증가)
• fix: 버그 수정 → 1.0.1 (Patch 버전 증가)
• BREAKING CHANGE: 포함된 커밋 → 2.0.0 (Major 버전 증가)

10. 테스트 및 배포

모든 설정이 완료되었으면, 코드 변경 후 커밋하고 푸시하면 GitHub Actions가 실행되며 NPM에 자동 배포됩니다.

git add .
git commit -m "feat: 첫 번째 기능 추가"
git push origin main

GitHub Actions에서 Workflow가 정상적으로 실행되었는지 확인하세요.

마무리

이제 semantic-release를 사용하여 NPM 패키지를 자동으로 배포하는 설정이 완료되었습니다. 앞으로는 Conventional Commits 규칙을 따라 커밋하면 자동으로 버전이 증가하고, 배포가 진행됩니다!

Troubleshooting

Github action 진행시 node vesion 문제

Run npx semantic-release
[semantic-release]: node version >=20.8.1 is required. Found v18.20.7.

See https://github.com/semantic-release/semantic-release/blob/master/docs/support/node-version.md for more details and solutions.
Error: Process completed with exit code 1.

.github/workflows/release.yml에 node-version을 수정

	...
	with:
    node-version: 20.9.0
    registry-url: "https://registry.npmjs.org/"
    ...