GitHub Pages로 정적 사이트 배포

들어가며

GitHub Pages는 별도 서버 없이 GitHub 저장소에서 바로 정적 사이트를 호스팅할 수 있는 서비스다.
포트폴리오, 문서 사이트, 블로그 등을 무료로 배포할 수 있다. 배포 방식을 제대로 정리해둔다.

---

GitHub Pages란?

GitHub 저장소의 특정 브랜치나 디렉토리를 기준으로 정적 파일을 호스팅하는 서비스다.

https://<username>.github.io               # 개인 페이지
https://<username>.github.io/<repository>  # 프로젝트 페이지

무료 플랜에서 공개 저장소는 무제한, 비공개 저장소는 GitHub Pro 이상에서 사용 가능하다.

---

배포 방식 두 가지

방식 1: 브랜치 직접 배포

특정 브랜치의 루트 또는 /docs 폴더를 그대로 배포하는 방식이다.

저장소 → Settings → Pages → Source → Deploy from a branch
브랜치: main 또는 gh-pages
폴더: / (root) 또는 /docs

방식 2: GitHub Actions로 배포 (권장)

빌드 과정이 필요한 프레임워크(React, Vue, Jekyll 등)에 적합하다.

저장소 → Settings → Pages → Source → GitHub Actions

---

실전 예시

순수 HTML/CSS/JS 배포

별도 빌드 없이 main 브랜치 루트를 그대로 배포한다.

저장소 루트
├── index.html
├── style.css
└── script.js

Settings → Pages → Deploy from a branch → main / root 선택 후 저장하면 자동 배포된다.

React 앱 배포 (GitHub Actions)

# .github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: 의존성 설치
        run: npm ci

      - name: 빌드
        run: npm run build

      - name: Pages 설정
        uses: actions/configure-pages@v4

      - name: 빌드 결과 업로드
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

      - name: 배포
        uses: actions/deploy-pages@v4

Vite 프로젝트 설정

GitHub Pages는 저장소 이름이 서브 경로로 붙기 때문에 vite.config.js에 base 설정이 필요하다.

// vite.config.js
export default {
  base: '/저장소이름/',
}

Jekyll 블로그 배포

Jekyll은 GitHub Pages에서 기본으로 지원한다. _config.yml만 설정하면 자동 빌드된다.

# _config.yml
title: wan의 개발일기
description: 개발 학습 기록
baseurl: "/blog"
url: "https://username.github.io"

---

커스텀 도메인 연결

구매한 도메인을 GitHub Pages에 연결할 수 있다.

1. 저장소 루트에 CNAME 파일 생성
   내용: www.example.com

2. 도메인 DNS 설정
   CNAME 레코드: www → username.github.io

3. Settings → Pages → Custom domain 입력
4. Enforce HTTPS 체크

---

주의사항

- 정적 파일만 호스팅 가능 (서버 사이드 로직 불가)
- 저장소 용량 1GB 이하 권장
- 월 100GB 소프트 대역폭 제한
- 빌드 시간 10분 제한
- 비공개 저장소는 GitHub Pro 이상 필요

---

정리

항목	내용
개인 페이지 URL	https://<username>.github.io
프로젝트 페이지 URL	https://<username>.github.io/<repo>
브랜치 직접 배포	빌드 없는 정적 파일에 적합
GitHub Actions 배포	React, Vue 등 빌드 필요한 경우
Vite base 설정	/저장소이름/ 경로 설정 필수
커스텀 도메인	CNAME 파일 + DNS 설정