Next.js Git Blog 자동 배포: GitHub Actions CI/CD
목차
소개#
글 작성이나 블로그 업데이트 횟수가 많지 않아 그냥 넘어가고 있었지만, Git Blog를 배포하는 과정에서 repository에 push하는 작업과 배포가 완전히 분리되어 있어 두 부분을 계속해서 신경 쓰며 관리하는 것이 너무 번거로웠다.
GitHub에 CI/CD 기능이 있는 것은 예전부터 알고 있었고 충분히 가능하다고 생각하고 있었지만, 미루고 미루다 지금에서야 사용해보고자 했다.
참고로 이 블로그는 Next.js의 static export 방식을 사용하고 있다.
수동 배포#
기존에는 Git repository에 올리는 것과는 별개로, 아래와 같은 설정과 배포 과정을 진행해야 했다.
package.json설정
"scripts": {
"dev": "next dev --turbopack",
"build": "next build",
"start": "next start",
"lint": "next lint",
"preview": "serve -s out",
"deploy": "touch out/.nojekyll && gh-pages -d out -b gh-pages --dotfiles"
}- 배포 과정
pnpm run build # 프로젝트 build
pnpm run deploy # 빌드 파일 배포즉, 코드를 repository로 push하는 것과 실제 배포 사이에 수동 작업이 항상 필요했다.
자동 배포#
내가 원하는 것은 main branch에 프로젝트를 push하면, 일련의 프로세스를 통해 build부터 배포까지 자동으로 진행되는 것이다.
이를 위해 GitHub Actions의 CI/CD를 구성했고, 준비는 아래와 같다. 하나씩 살펴보도록 하자.
- Workflow yml 스크립트 작성
- GitHub Pages 설정
Workflow yml 스크립트 작성
먼저 아래와 같은 Workflow yml 스크립트를 작성하여 프로젝트 내부(.github/workflows/deploy.yml)에 위치시켜야 한다.
# Workflow 이름 (GitHub Actions 탭에 표시됨)
name: Deploy Git Blog
# Workflow가 실행될 조건
# main 브랜치에 push가 발생할 때 자동 실행
on:
push:
branches:
- main
# GitHub Pages 배포를 위해 repository contents 쓰기 권한 부여
permissions:
contents: write
jobs:
deploy:
# 실행 환경 (GitHub에서 제공하는 Ubuntu 최신 버전)
runs-on: ubuntu-latest
steps:
# 현재 repository 코드 checkout
- name: Checkout
uses: actions/checkout@v4
# pnpm 설치
# 메이저 버전만 고정하여 lockfile 변경 위험 최소화
- name: Setup pnpm
uses: pnpm/action-setup@v3
with:
version: 10
# Node.js 환경 설정
# 메이저 버전만 고정하여 안정성과 유지보수를 고려
# pnpm 캐시를 사용해 의존성 설치 속도 향상
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
# 의존성 설치
- name: Install dependencies
run: pnpm install
# 프로젝트 build
# Next.js static export 결과물이 out 디렉터리에 생성됨
- name: Build & Export
run: pnpm run build
# GitHub Pages에서 Jekyll 처리를 비활성화
# (_next, 파일명에 '_'가 포함된 경우 제거되는 현상 방지)
- name: Disable Jekyll
run: touch out/.nojekyll
# 빌드된 결과물을 gh-pages 브랜치로 배포
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
with:
# GitHub에서 자동으로 제공되는 토큰
github_token: ${{ secrets.GITHUB_TOKEN }}
# 배포할 디렉터리
publish_dir: ./outGitHub Pages 설정
이미 Git Blog를 운영중이라면 잘 적용이 되어있겠지만, 다시 한 번 설정이 제대로 되어있는지 확인하자.
- Settings → Pages
- Source:
- Branch:
gh-pages - Folder:
/
- Branch:
위 두 설정의 준비가 완료되면 main 브랜치에 코드가 push될 때마다, GitHub Actions가 자동으로 실행되어 프로젝트를 build하고 결과물을 gh-pages 브랜치에 배포하게 된다.
이제 로컬 환경에서는 별도의 배포 명령어를 실행할 필요 없이, repository로 push만 하게 되면 자동으로 배포가 될 것이다.
그림 1. CI/CD workflow가 정상적으로 완료된 모습
평가#
관리 포인트가 하나로 줄어드면서 전반적으로 운영이 훨씬 편해졌다. 이런 방식이라면 마크다운 파일만 따로 관리하는 브랜치를 만들고 관리할 수도 있겠다는 생각이 들었다.
다만 프로젝트 자체도 계속해서 수정/확장이 될 것 같으니, 일단은 현재 구조를 유지하는게 더 절적한 것 같다.