GitHub Pages에 GitHub Action으로 React와 Vite 배포 자동화 (CI/CD)

GitHub Pages에 React와 Vite로 만든 웹사이트를 GitHub Actions를 사용하여 자동으로 배포하는 방법을 알아봅니다.

react 19.2.5

2026년 1월 24일

GitHub Pages는 정적 웹사이트를 호스팅하는 서비스로, 개인 프로젝트나 포트폴리오 사이트를 쉽게 배포할 수 있습니다. 이번 글에서는 React와 Vite로 만든 웹사이트를 GitHub Actions를 사용하여 자동으로 GitHub Pages에 배포하는 방법을 알아보겠습니다.

GitHub Actions를 사용해서 배포하면 좋은점

GitHub Actions를 사용하면 코드가 변경될 때마다 자동으로 빌드하고 배포할 수 있습니다. 이를 통해 수동으로 배포하는 번거로움을 줄이고, 항상 최신 버전의 웹사이트를 유지할 수 있습니다.

GitHub Pages는 유료 플랜 사용자가 아니라면 반드시 퍼블릭 저장소에서만 사용할 수 있습니다.

GitHub Pages 설정

먼저, GitHub Pages를 설정해야 합니다. 저장소의 Settings 탭으로 이동한 후, Pages 섹션에서 Build and deployment를 GitHub Actions로 선택, 설정합니다.

GitHub Pages 설정 화면

GitHub Actions 워크플로우 파일 생성

이제 GitHub Actions 워크플로우 파일을 생성합니다. 저장소의 루트 디렉토리에 .github/workflows 폴더를 만들고, 그 안에 deploy-pages.yml 파일을 생성합니다.

프로젝트 디렉토리 구조 예시

my-app

.github

workflows

deploy-pages.yml

워크플로우 파일에 다음 내용을 추가합니다:

저는 pnpm을 사용하고 있으므로 pnpm 설정이 포함되어 있습니다. npm이나 yarn을 사용하신다면 해당 부분을 적절히 변경해주세요.

deploy-pages.yml

name: Deploy Vite (pnpm) to GitHub Pages
 
on:
  push:
    branches: ["main"]
  workflow_dispatch:
 
permissions:
  contents: read
  pages: write
  id-token: write
 
concurrency:
  group: "pages"
  cancel-in-progress: true
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/configure-pages@v5
 
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
 
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10
          run_install: false
 
      - name: Check pnpm
        run: pnpm -v
 
      - name: Install
        run: pnpm install --frozen-lockfile
 
      - name: Build
        run: pnpm run build
 
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist
 
  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

이 워크플로우는 main 브랜치에 푸시될 때마다 실행되며, Vite 프로젝트를 빌드하고 dist 폴더의 내용을 GitHub Pages에 배포합니다.

다음은 vite에서 설정이 필요합니다.

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
 
export default defineConfig({
  plugins: [react()],
  base: "/REPO_NAME/", // <- 여기를 자신의 저장소 이름으로 변경하세요
});

다음은 package.json에서 배포 스크립트를 설정하는 예시입니다.

package.json

{
  "homepage": "https://USERNAME.github.io/REPO_NAME/", // <- 여기를 자신의 GitHub 사용자 이름과 저장소 이름으로 변경하세요
  "scripts": {
    "build": "tsc -b && vite build && cp dist/index.html dist/404.html"
  }
}

Vite 프로젝트의 경우, `base` 옵션을 설정하여 GitHub Pages에서 올바르게 작동하도록 해야 합니다. 또한, `404.html` 파일을 복사하는 것은 GitHub Pages에서 SPA 라우팅 문제를 방지하는 데 도움이 됩니다.

커밋 및 푸시

모든 변경 사항을 커밋하고 main 브랜치에 푸시합니다.

git add .
git commit -m "Set up GitHub Actions for GitHub Pages deployment"
git push origin main

푸시가 완료되면 GitHub 저장소의 Actions 탭에서 워크플로우가 실행되는 것을 확인할 수 있습니다. 빌드와 배포가 성공적으로 완료되면, 설정한 GitHub Pages URL에서 웹사이트를 확인할 수 있습니다.

이제 React와 Vite로 만든 웹사이트가 GitHub Pages에 자동으로 배포됩니다! GitHub Actions를 사용하여 CI/CD 파이프라인을 구축함으로써, 코드 변경 시마다 최신 버전의 웹사이트를 쉽게 유지할 수 있습니다.

Expo 프로젝트 iOS Test Flight 배포 가이드 (feat. xCode)

GitHub Pages에 GitHub Action으로 React와 Vite 배포 자동화 (CI/CD)

GitHub Pages에 React와 Vite로 만든 웹사이트를 GitHub Actions를 사용하여 자동으로 배포하는 방법을 알아봅니다.

react 19.2.5

2026년 1월 24일

프로젝트 디렉토리 구조 예시

my-app

.github

workflows

deploy-pages.yml

워크플로우 파일에 다음 내용을 추가합니다:

저는 pnpm을 사용하고 있으므로 pnpm 설정이 포함되어 있습니다. npm이나 yarn을 사용하신다면 해당 부분을 적절히 변경해주세요.

deploy-pages.yml

name: Deploy Vite (pnpm) to GitHub Pages
 
on:
  push:
    branches: ["main"]
  workflow_dispatch:
 
permissions:
  contents: read
  pages: write
  id-token: write
 
concurrency:
  group: "pages"
  cancel-in-progress: true
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/configure-pages@v5
 
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
 
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10
          run_install: false
 
      - name: Check pnpm
        run: pnpm -v
 
      - name: Install
        run: pnpm install --frozen-lockfile
 
      - name: Build
        run: pnpm run build
 
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist
 
  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

이 워크플로우는 main 브랜치에 푸시될 때마다 실행되며, Vite 프로젝트를 빌드하고 dist 폴더의 내용을 GitHub Pages에 배포합니다.

다음은 vite에서 설정이 필요합니다.

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
 
export default defineConfig({
  plugins: [react()],
  base: "/REPO_NAME/", // <- 여기를 자신의 저장소 이름으로 변경하세요
});

다음은 package.json에서 배포 스크립트를 설정하는 예시입니다.

package.json

{
  "homepage": "https://USERNAME.github.io/REPO_NAME/", // <- 여기를 자신의 GitHub 사용자 이름과 저장소 이름으로 변경하세요
  "scripts": {
    "build": "tsc -b && vite build && cp dist/index.html dist/404.html"
  }
}

커밋 및 푸시

모든 변경 사항을 커밋하고 main 브랜치에 푸시합니다.

git add .
git commit -m "Set up GitHub Actions for GitHub Pages deployment"
git push origin main

Expo 프로젝트 iOS Test Flight 배포 가이드 (feat. xCode)