changeset과 github action으로 버전 관리하기

changeset과 github action으로 버전 관리하기

얼마 전에 Notion 관련 유틸을 만들면서 npm에 라이브러리를 배포했는데, 수동으로 버전 관리를 하는 것이 번거로웠다. 그래서 이를 해결하기 위해 changeset과 GitHub Action을 도입하게 되었다. 한글로 된 포스팅이 많지 않아, 이번 기회에 공유하고자 한다.

버전 관리

Semver

Semver(Semantic Versioning)는 버전 번호를 의미 있게 관리하기 위한 규칙으로, 주.부.수 형식으로 표현된다.
주요 버전(major)은 호환되지 않는 변경 사항이 있을 때, 부 버전(minor)은 호환되는 새로운 기능이 추가될 때, 수 버전(patch)은 버그 수정 등 하위 호환 가능한 변경이 있을 때 업데이트한다.
이러한 SemVer 규칙을 사용하면 버전 번호만 보고도 변경의 성격을 쉽게 파악할 수 있어 개발자와 사용자 모두에게 큰 도움이 된다.
모든 라이브러리는 위 규칙으로 관리된다.

changeset

A tool to manage versioning and changelogs with a focus on multi-package repositories
changesets
changesetsUpdated Jan 17, 2025
changeset은 코드 변경 사항을 기록하고, 이를 기반으로 패키지의 버전을 효율적으로 관리할 수 있게 해주는 도구이다. 보통 라이브러리나 모노레포(monorepo) 환경에서 많이 사용되며, 여러 패키지의 변경 사항을 관리하거나 여러 개발자가 협업하는 상황에서 특히 유용하다.
changeset의 장점 중 하나는 다중 패키지 관리를 쉽게 할 수 있다는 점이다. 모노레포에서는 여러 패키지가 하나의 저장소에 포함되어 있어 각 패키지의 변경 사항을 관리하는 것이 까다로울 수 있는데, changeset은 이를 간단하게 만들어 준다. 또한 GitHub와의 통합을 통해 CI/CD 파이프라인에서 자동으로 버전 관리 및 배포 과정을 수행할 수 있어, 개발자들이 수동으로 버전을 관리하는 번거로움을 줄여준다.

사용 방법

changeset을 프로젝트에 설정하는 과정은 비교적 간단하다. 다음 단계들을 통해 changeset을 설정할 수 있다. (pnpm 기준으로 설명한다! npm, yarn과 별다른 차이는 없다)
1. changeset 설치: 먼저 프로젝트에 changeset을 설치해야 한다. pnpm을 사용해 changeset을 설치할 수 있다.
설치 후, changeset을 초기화한다.
이 명령을 실행하면 프로젝트 루트에 .changeset 폴더가 생성되고, 기본적인 설정 파일들이 만들어진다.
2. 변경 사항 기록하기: 새로운 기능 추가나 버그 수정 등의 변경 사항이 있을 때, changeset을 통해 변경 사항을 기록한다.
이 명령을 실행하면 아래 사진과 같이 변경의 유형(major, minor, patch)과 변경된 패키지에 대해 설명을 입력하는 인터페이스가 나타난다. 이를 통해 변경 사항을 문서화할 수 있다.
notion image
notion image
notion image
변경사항이 임의의 파일명을 가진 md에 기록되었다.
3. 버전 업데이트 및 변경 로그 생성: 모든 변경 사항이 기록되면, changeset은 이를 기반으로 버전을 업데이트하고 변경 로그를 생성한다. 로컬에서 수동으로 실행할 경우 다음 명령을 사용한다.
notion image
notion image
위 커맨드를 입력하니 기존 md이 사라지고, CHANGELOG.md에 변경 사항이 버전과 함께 기록되고 package.json 에 버전도 자동으로 올라갔다.
4. 배포: changeset을 사용해 변경 사항을 기록하고 버전을 업데이트한 후, 다음 명령으로 배포할 수 있다.
이 명령을 실행하면 새로운 버전이 npm에 자동으로 배포된다.
이렇게 changeset을 설정하면, 프로젝트 내의 모든 변경 사항을 체계적으로 관리하고, 자동으로 버전 및 변경 로그를 생성할 수 있어 협업과 유지보수가 훨씬 수월해진다.
여기까지 다 좋은데 패키지의 기능을 추가 및 수정하고 커밋 후, changeset를 통해 배포를 하면 CHANGELOG에 변경사항이 생겨서 또 커밋을 해야 한다. 그리고 아래와 같이 생각보다 입력해야 할 커맨드 양이 꽤 있다.
다행히 changeset에서 github action workflow를 만들어 놓아서 --- 로 시작해서 끝나는 커맨드들을 workflow과 pull request를 통해 자동화할 수 있다.

changeset과 GitHub Action의 통합

Github Action

GitHub Action은 GitHub 저장소에서 빌드, 테스트, 배포 같은 작업을 자동화할 수 있는 도구이다. 이를 통해 개발자는 반복적인 작업을 자동으로 처리하고, CI/CD 파이프라인을 쉽게 구성할 수 있다. (GitHub Action은 짧게만 설명하고 넘어간다..)

npm 토큰 발급

notion image
notion image
우선 npm 토큰을 발급받아야 한다. 위 사진처럼 Access Tokens를 클릭해서 Generate New Token → Classic Token를 클릭하자!
notion image
notion image
type를 Automation으로 선택해 토큰을 발급받고 복사하자. (잃어버리면 안 된다.. 위 테스트용 토큰은 발급받자마자 지웠다.)
그리고 github로 이동해서 발급받은 토큰을 원하는 Repository에 설정해준다.
notion image
위 사진에서 New repository secret를 눌러 아래와 같이 설정하고 추가한다. Name: NPM_TOKEN, Secret: 발급 받은 토큰
notion image
Workflow permission에 위와 같은 권한이 없으면 PR 생성이 안되니 위 설정도 확인해 보자!
다음으로 배포를 자동화하기 위한 Github Action을 설정한다. 아래는 GitHub Action 설정 파일(.github/workflows/release.yml)의 예시이다. (각 라인의 설명도 함께 추가하였다.)
release.yml
위 yml파일의 마지막 step에서 아래와 같이 version, publish 설정을 해주는데, 이건 나의 package.json script에 추가해 준 changeset 관련 명령어다.
 

직접 해보기

자! 이제 세팅은 다 끝났다. 그럼 위 github action은 어떻게 작동할까? 직접 해보자!
위 커맨드는 git alias를 사용한 커맨드다! (그냥 add, commit, push다)
push를 하면 workflow 실행되면서 PR이 생성된다.
notion image
notion image
notion image
자동으로 생성된 file changed
자동으로 생성된 file changed
github-actions 봇이 자동으로 PR을 생성했고 위와 같이 내용도 친절하게 적어준다. 마지막으로 해당 PR를 머지하면 아래와 같이 다시 workflow가 실행되며 npm에 배포된다.
notion image
notion image
npm에 배포된 결과
npm에 배포된 결과
위 실행 결과를 보면 알겠지만 같은 Create Release Pull Request or Publish to npm action이 수행되는데 어떤 경우는 PR이 생성되고 어떤 경우는 npm에 배포되며 release tag가 생성된다.
그 이유는 changesets/action@v1 의 내부 코드를 보면 알 수 있다.
간단하게 설명하면 동작을 결정하는 기준은 changeset 상태트리거된 변경 사항에 따라 달라진다.
  • PR 생성: changeset 파일이 새롭게 추가되고, 아직 버전 업데이트 및 Release 승인이 이루어지지 않은 경우
  • npm 배포: Release PR이 main 브랜치에 병합되어 모든 준비가 완료된 경우

마무리

이로써 changeset과 github action을 활용해 버전 관리를 자동화하는 방법을 모두 설명했다. 추가, 수정할 내용만 커밋하고 changeset를 활용해 버전의 주.부.수 를 선택하고 push하면 PR 생성과 npm 배포, release tag까지 자동으로 수행해 준다. 버전 관리는 특히 여러 사람과 협업할 때 매우 중요한데 PR를 통해 다른 사람들이 편하게 확인할 수 있어 더욱 큰 장점이 된다!
주제에 대한 설명을 여기까지 하고, 이번에 글또 10기를 시작하며 처음 쓰는 글인데 거의 5개월 만의 글이라 익숙지 않았지만 AI를 활용해서 자료 찾기와 글쓰기가 조금 더 빨라졌다! 글또 10기 파이팅~

Reference