Conventional Commits 기반으로 changelog을 자동 생성하고, GitHub Release를 만드는 GitHub Action 활용법을 정리한다.
requarks/changelog-action은 git 태그 사이의 커밋을 분석하여 Markdown 형식의 changelog을 생성하는 GitHub Action이다. PR 링크, 작성자 표시, BREAKING CHANGE 강조 등을 자동으로 처리한다.
BREAKING CHANGE 노트를 버전 항목 상단에 배치v* (예: v0.2.3)type(scope): description
[optional body]
[optional footer(s)]
| Type | 설명 |
|---|---|
feat |
새로운 기능 추가 |
fix |
버그 수정 |
refactor |
리팩토링 (기능 변경 없음) |
docs |
문서 변경 |
test |
테스트 추가/수정 |
chore |
빌드, 설정 등 기타 변경 |
ci |
CI/CD 설정 변경 |
perf |
성능 개선 |
build |
빌드 시스템 변경 |
style |
코드 포맷팅 변경 |
| 파라미터 | 필수 | 기본값 | 설명 |
|---|---|---|---|
token |
O | — | GitHub API 토큰 (${{ github.token }}) |
tag |
O* | — | 현재 태그 (단일 태그 모드) |
fromTag |
O* | — | 범위의 시작 태그 |
toTag |
O* | — | 범위의 끝 태그 |
excludeTypes |
X | build,docs,other,style |
제외할 커밋 타입 (쉼표 구분) |
excludeScopes |
X | — | 제외할 scope (쉼표 구분) |
restrictToTypes |
X | — | 특정 타입만 포함 (excludeTypes 무시) |
writeToFile |
X | true |
CHANGELOG.md 파일 자동 생성 |
changelogFilePath |
X | CHANGELOG.md |
changelog 파일 경로 |
includeInvalidCommits |
X | false |
비표준 커밋 포함 여부 |
useGitmojis |
X | true |
타입 헤더에 이모지 표시 |
reverseOrder |
X | false |
최신 커밋 먼저 표시 |
tag와fromTag/toTag는 택일 관계이다. 단일 태그 모드에서는 이전 태그를 자동으로 찾는다.
| 출력 | 설명 |
|---|---|
changes |
생성된 changelog 내용 (버전/날짜 헤더 제외) |
npm 패키지 자동 배포 워크플로우에 changelog 생성을 추가하는 실제 적용 사례이다.
name: Publish to npm
on:
push:
tags:
- 'v*'
jobs:
ci:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [20, 22]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm
- run: npm ci
- run: npm run check
- run: npm run build
- run: npm test
publish:
needs: ci
runs-on: ubuntu-latest
permissions:
contents: write # GitHub Release 생성에 필요
id-token: write # npm Trusted Publishing
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # 전체 히스토리 (이전 태그 비교용)
- uses: actions/setup-node@v4
with:
node-version: 24
registry-url: https://registry.npmjs.org
cache: npm
- run: npm ci
- run: npm run build
- name: Verify tag matches package.json version
run: |
PKG_VERSION="v$(node -p "require('./package.json').version")"
GIT_TAG="${GITHUB_REF#refs/tags/}"
if [ "$PKG_VERSION" != "$GIT_TAG" ]; then
echo "::error::Tag $GIT_TAG does not match package.json version $PKG_VERSION"
exit 1
fi
- name: Generate changelog
id: changelog
uses: requarks/changelog-action@v1
with:
token: ${{ github.token }}
tag: ${{ github.ref_name }}
writeToFile: false
excludeTypes: build,docs,other,style,ci,test,chore
- name: Create GitHub Release
uses: ncipollo/release-action@v1
with:
allowUpdates: true
body: ${{ steps.changelog.outputs.changes }}
tag: ${{ github.ref_name }}
- run: npm publish --provenance --access public
fetch-depth: 0- uses: actions/checkout@v4
with:
fetch-depth: 0 # 기본값 1 → 전체 히스토리로 변경
fetch-depth: 0이 없으면 이전 태그를 찾을 수 없어 action이 실패한다. 반드시 설정해야 한다.
contents: write 권한permissions:
contents: write # read → write 변경
GitHub Release 생성에는 contents: write 권한이 필요하다. CHANGELOG.md를 커밋하는 경우에도 동일하게 필요하다.
excludeTypes 커스터마이징# 사용자 대상 변경사항만 포함 (feat, fix, refactor)
excludeTypes: build,docs,other,style,ci,test,chore
# 모든 커밋 타입 포함
excludeTypes: ''
# 기본값 사용 (build, docs, other, style 제외)
# excludeTypes 생략
프로젝트 규모와 목적에 따라 선택한다. 소규모 프로젝트에서는 모든 타입을 포함하는 것이 좋고, 사용자용 릴리즈 노트에는 feat, fix, refactor만 포함하는 것이 깔끔하다.
GitHub Release 본문에만 사용하지 않고 CHANGELOG.md 파일도 저장소에 유지하려면:
- name: Generate changelog
id: changelog
uses: requarks/changelog-action@v1
with:
token: ${{ github.token }}
tag: ${{ github.ref_name }}
writeToFile: true # CHANGELOG.md 자동 생성
excludeTypes: build,docs,other,style,ci,test,chore
- name: Commit CHANGELOG.md
uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: 'docs: update CHANGELOG.md for ${{ github.ref_name }}'
file_pattern: CHANGELOG.md
branch: develop
writeToFile: true로 설정하면 CHANGELOG.md에 새 버전 항목이 추가된다. 이미 동일 버전이 있으면 중복 추가하지 않는다.
changelog-action이 생성하는 결과물 예시:
### ✨ Features
- [`a1b2c3d`](https://github.com/owner/repo/commit/a1b2c3d) - Add client-side fallback for PAGES mode *(by @username)*
### 🐛 Bug Fixes
- [`d4e5f6g`](https://github.com/owner/repo/commit/d4e5f6g) - Fix query builder compatibility issue *(by @username)*
### ♻️ Refactoring
- [`h7i8j9k`](https://github.com/owner/repo/commit/h7i8j9k) - Extract fetchTree helper function *(by @username)*
v0.0.0)를 만들어 두면 된다.release:) — includeInvalidCommits: true로 포함 가능하지만, Conventional Commits 표준 타입(예: chore(release):)을 사용하는 것이 권장된다.excludeScopes)을 활용하여 패키지별 changelog을 분리할 수 있다.