얼마 전에 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
changesets • Updated 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)과 변경된 패키지에 대해 설명을 입력하는 인터페이스가 나타난다. 이를 통해 변경 사항을 문서화할 수 있다.
변경사항이 임의의 파일명을 가진 md에 기록되었다.
3. 버전 업데이트 및 변경 로그 생성: 모든 변경 사항이 기록되면, changeset은 이를 기반으로 버전을 업데이트하고 변경 로그를 생성한다. 로컬에서 수동으로 실행할 경우 다음 명령을 사용한다.
위 커맨드를 입력하니 기존 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 토큰 발급
우선 npm 토큰을 발급받아야 한다. 위 사진처럼 Access Tokens를 클릭해서 Generate New Token → Classic Token를 클릭하자!
type를 Automation으로 선택해 토큰을 발급받고 복사하자.
(잃어버리면 안 된다.. 위 테스트용 토큰은 발급받자마자 지웠다.)
그리고 github로 이동해서 발급받은 토큰을 원하는 Repository에 설정해준다.
위 사진에서 New repository secret를 눌러 아래와 같이 설정하고 추가한다.
Name:
NPM_TOKEN, Secret: 발급 받은 토큰
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이 생성된다.
github-actions 봇이 자동으로 PR을 생성했고 위와 같이 내용도 친절하게 적어준다.
마지막으로 해당 PR를 머지하면 아래와 같이 다시 workflow가 실행되며 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기 파이팅~