gitHub Pages에서 정적 사이트를 배포할 때, Source의 Build and deployment 설정과
GitHub Actions는 둘 다 배포를 위한 도구이지만, 목적과 활용 방법이 다르다.

항목	Deploy from Branch	GitHub Actions
설정 위치	Settings > Pages	.github/workflows/
자동 빌드 여부	❌ 수동 빌드 후 커밋 필요	✅ push 시 자동 빌드·배포
정적 파일 경로	직접 지정 (/docs, /)	빌드 결과(dist) 자동 처리
유연성	낮음	높음
권장 대상	HTML/CSS 단순 정적 사이트	React / Vue / Vite 등 빌드 필요 프로젝트

이번 포스팅 에서는 Vite + React 정적 자원 프로젝트를 GitHub Actions로 자동 빌드 & 자동 배포하는 전체 흐름을 다룬다.
레포지토리 이름과 vite.config.js의 base 설정을 일치시키고, git push만 하면 자동으로 배포가 이루어지도록 구성한다.

---

Vite 프로젝트 생성

공식 문서: https://ko.vite.dev/guide/

npm create vite@latest my-app
# React, JavaScript 선택

cd my-app
npm install
npm run dev

로컬 실행 주소:
http://localhost:5173/

---

GitHub 저장소 준비

GitHub에서 새 저장소를 만든 뒤 다음 명령으로 연결한다.

git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/kglim1004/my-app.git
git push -u origin main

---

로컬 프로젝트에 GitHub 원격 연결

git init
git remote add origin https://github.com/kglim1004/....git
git add .
git commit -m "init"
git push -u origin master

브랜치/원격 상태 확인:

명령어	설명
git branch	현재 체크아웃된 브랜치
git remote show origin	원격 저장소 정보
GitHub → Settings → Branches	기본 브랜치 설정

자동 배포는 반드시 기본 브랜치(main 또는 master) 기준으로 동작하므로 이름을 일치시켜야 한다.

---

GitHub Pages 설정

GitHub Repository →
Settings → Pages → Build and Deployment → Source: GitHub Actions

Pages를 GitHub Actions 기반 배포로 사용하겠다는 뜻이다.
(수동 업로드가 아니라 CI/CD 기반 자동 배포)

---

GitHub Actions 워크플로우 추가

프로젝트에 다음 구조 생성:

my-app
 └─ .github
     └─ workflows
         └─ deploy.yml

deploy.yml 내용:

name: Deploy static content to Pages

on:
  push:
    branches: ['master']
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

---

Vite base 설정

GitHub Pages는 프로젝트를 /레포지토리명/ 경로에서 서빙한다.
React Router, JS, CSS 경로가 정상적으로 동작하기 위해 vite.config.js의 base를 repo 이름과 동일하게 맞춘다.

예: repo 이름이 my-app이면

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: "/my-app/",
})

이 base 설정을 하지 않으면 빌드 후 JS/CSS 파일 경로가 모두 깨져서 화면이 흰색으로 뜨게 된다.

---

git push → 자동 배포

CI/CD가 완성되었으므로 다음 명령만 실행하면 자동으로 배포된다.

git add --all
git commit -m "deploy setup"
git push

GitHub Actions가 자동으로 다음을 수행한다:

• Node 환경 설치
• npm ci
• Vite 빌드 → dist 생성
• dist를 Pages 환경에 업로드
• 최종 사이트 배포 완료

---

배포 주소 확인

Actions에서 성공 표시가 나면 아래 URL로 접속:

https://{username}.github.io/{repo-name}/
https://billiondollarsohee.github.io/my-app/

---

열리지 않을 때 체크할 것

• vite.config.js의 base 경로 확인
• GitHub Pages Source가 GitHub Actions인지 확인
• 기본 브랜치(master/main) 이름 일치 확인
• dist 폴더가 정상 생성되었는지 Actions 로그에서 확인
• 브라우저 캐시 삭제하고 재접속

---

GitHub Actions 실패 원인과 해결

Branch "master" is not allowed to deploy

• GitHub Pages 환경 보호 규칙이 활성화되어 있을 때 발생
• Pages의 Environment가 github-pages로 되어 있고 write 권한이 허용되어야 함

base 설정 누락

• 화면은 뜨지만 JS/CSS 404 → 실행 안 됨
• 반드시 base: "/repo-name/" 필요

npm ci 실패

• package-lock.json 문제
• 해결: node_modules + package-lock 삭제 후 재설치

artifact 업로드 실패

• dist 폴더가 생성되지 않음 → 빌드 실패
• Actions 빌드 로그 확인 필수

---

CI/CD 전체 흐름 요약

개발 → git push → GitHub Actions 실행  
→ Vite 빌드(dist 생성)  
→ dist를 GitHub Pages에 업로드  
→ https://username.github.io/repo-name/ 로 자동 배포

리액트·정적 자원 프로젝트를 위한 완전 자동 배포 파이프라인이 완성된다.

---