프론트엔드 깃허브 액션 CI 시스템을 이용한 버전관리

개요

네이티브 앱에 WebView 형태로 연동되는 프로젝트를 진행하면서 버전 관리 자동화의 필요성을 느꼈습니다.

테스트 브랜치 기준으로 QA 환경을 운영하는 상황에서, 브라우저 캐시등의 문제로 인해 배포가 실제로 적용됐는지를 파악하기 어려운 상황이 종종 발생했기 때문인데요.

GitHub Actions 기반의 CI 환경을 활용해 '버전 자동 증분 및 QA 확인을 위한 워크플로우 구성'의 설계 과정을 적습니다.

 

 

개념에 대한 언급

CI(Continuous Integration)는 '지속적 통합'의 줄임말.
코드가 변경될 때마다 자동으로 빌드, 테스트, 배포 등을 수행해주는 일련의 자동화 프로세스를 말합니다.

 

GitHub Actions는 깃허브 저장소에서 이벤트에 반응해 실행되는 자동화 작업 단위(액션) 를 정의할 수 있는 도구입니다.

대부분의 개발자들이 GitHub 계정을 보유하고 있어 진입 장벽이 낮으며, 복잡한 설정을 희생하는 대신 접근성을 극대화하였습니다.

 

 

진행 방식

- package.json 수정

"scripts": {
	"version:patch": "npm version --no-git-tag-version prepatch --preid=0",
	"version:bump": "npm version --no-git-tag-version prerelease",
	"version:deploy": "npm run version:patch && npm run build:dev",
	"version:rebuild": "npm run version:bump && npm run build:dev"
},

• version:patch: 기존 버전을 기준으로 prepatch(예: 1.0.0 → 1.0.1-0) 버전 생성.
• version:bump: prerelease 버전을 증분 (예: 1.0.1-0 → 1.0.1-1).
• version:deploy: patch와 build를 함께 수행.
• version:rebuild: bump와 build를 함께 수행.

prerelease version을 두어 QA 과정을 통한 rebuild에서 patch의 증분 최소화를 의도했습니다.

 

- .github/workflows 경로에 .yml 파일 생성

name: QA Version Bump
on:
  push:
    branches: [test]
concurrency:
  group: test-${{ github.ref }}
  cancel-in-progress: true
jobs:
  bump:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Pull & Rebase
        run: git pull origin test --rebase

      - uses: actions/setup-node@v3
        with:
          node-version: 23.x

      - name: Clean Install
        run: |
          rm -rf node_modules package-lock.json
          npm install

      - name: Create .env.development from secret
        run: |
          echo "${{ secrets.ENV_DEVELOPMENT }}" > .env.development

      - name: Version Bump Logic
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "[bot]@users.noreply.github.com"

          if [[ "$(git log -1 --pretty=%B)" == *"patch:"* ]]; then
            npm run version:rebuild
          else
            npm run version:deploy
          fi

          git add .
          git commit -m "Bump QA version [skip ci]"
          git push origin test

 

• 트리거: test 브랜치에 push가 일어나면 워크플로우가 실행.
• 버전 증분 타입 판단: 커밋 메시지에 "patch:"가 포함되어 있으면 rebuild, 아니면 deploy로 판단.
  (현재 git log -1만 바라보기 때문에 직전 commit의 "patch:"가 아니라면 deploy로 판단합니다.
  따라서, git squash를 통해 적절히 명칭을 수정해 build 하여야 하며, 추후 개선의 대상으로 남겨두도록 합니다.)
• 버전 스크립트 실행: 설정된 타입에 따라 npm run version:deploy 또는 npm run version:rebuild 스크립트를 실행 -> 버전을 자동 증분하고 빌드한 후, 커밋과 푸시.

 

 

 

에러 상황

- [CI 에러] npm error code EUSAGE

npm ci can only install with an existing package-lock.json or npm-shrinkwrap.json with lockfileVersion >= 1

 

원인: 저장소에 package-lock.json 파일이 없음.

해결: 해당 파일을 반드시 버전 관리에 포함 (git add package-lock.json)후,

CI 환경에서 npm ci 명령어로 정확한 의존성 설치 보장.

 

- [CI 에러] npm ci 에러

Error: Cannot find module @rollup/rollup-linux-x64-gnu.
npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828).
Please try `npm i` again after removing both package-lock.
json and node_modules directory.

 

원인: CI 환경에서 플랫폼별 선택적 의존성이 누락될 때 발생.

해결: 선택적 의존성을 package.json에 명시적으로 추가하고 CI 환경에서 플랫폼별 패키지 강제 설치 설정.

 

- [CI 에러] 워크플로우 권한 설정 문제

fatal: unable to access 'https://{생략}': The requested URL returned error: 403
Error: Process completed with exit code 128.

 

원인: GitHub 저장소 권한 부족.

해결: yaml 파일에서 직접 권한 지정.

permissions:
  contents: write

YAML에서의 권한 지정은 저장소 전역 설정을 무시합니다.

 

- [build 에러] git 병합 충돌

build 파일 상단에 '<<<< HEAD ==== >>'같은 문자가 존재.

원인: Git 병합 충돌이 자동화 프로세스 중에 해결되지 않고 커밋되었기 때문.

- name: Pull & Rebase
  run: git pull origin test --rebase

해결: 워크플로우 시작 시 최신 변경 사항을 반영할 수 있도록 합니다.