GitHub Pages — 저장소를 정적 사이트로

GitHub Pages 는 GitHub 저장소를 그대로 정적 웹사이트로 배포하는 무료 호스팅입니다. HTML/CSS/JS 또는 Jekyll/Hugo/Vite 같은 정적 사이트 생성기 (SSG) 의 빌드 산출물을 그대로 서빙합니다.

1. GitHub Pages 의 자리

시기	사건
2008	Tom Preston-Werner 가 GitHub 와 같이 발표 (Jekyll 기반).
2014 ~	HTTPS 무료 (Let's Encrypt 통합 이전 → custom domain 도 HTTPS).
2018 ~	GitHub Actions 통합 — 임의 SSG (Hugo · Vite · Astro …) 가능.
2022 ~	Actions 기반 배포가 default 추천 (이전 branch 기반 배포 대체).

핵심 가치 제안:

• 저장소 = 사이트. 무료 + 무제한 트래픽 (한 달 100GB soft-limit, 빌드 10/h).
• HTTPS · custom domain · CDN 모두 기본 제공.
• 정적 사이트 한정. 백엔드 / DB 없음.

2. 두 가지 배포 모드

(a) 기본 — 브랜치 직접 서빙

저장소의 특정 브랜치 (보통 main 또는 gh-pages) 의 루트나 /docs 폴더를 그대로 서빙. SSG 가 사전에 빌드한 dist/ 를 push 합니다. 단순한 정적 사이트에 적합.

(b) 권장 — GitHub Actions 빌드 후 배포

.github/workflows/deploy.yml 에서 빌드 → artifact 업로드 → Pages 배포. 임의 SSG 사용 가능. 2022 부터 default.

# .github/workflows/deploy.yml — Vite 예시
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: github-pages
    steps:
      - uses: actions/deploy-pages@v4

3. URL 패턴

저장소 종류	URL
<user>.github.io (User site)	https://<user>.github.io/
<org>.github.io (Org site)	https://<org>.github.io/
<user>/<repo> (Project site)	https://<user>.github.io/<repo>/
Custom domain	https://example.com/

Project site 는 path prefix 가 /<repo> — Vite 의 base: '/<repo>/' · Next.js 의 basePath 등 설정 필수. user/org site 는 prefix 없음.

4. Custom domain

CNAME 파일

저장소 루트에 CNAME 파일 (한 줄에 도메인) 추가하거나 GitHub UI 에서 설정. GitHub 가 DNS 안내 표시.

DNS 설정

• apex (example.com) — A 레코드 4개 (185.199.108.153 · 185.199.109.153 · 185.199.110.153 · 185.199.111.153)
• www / 서브도메인 — CNAME → <user>.github.io

GitHub UI 에서 "Enforce HTTPS" 체크 (Let's Encrypt 자동 발급).

5. 환경변수 / Secrets

빌드 시점에는 GitHub Actions Secrets (Settings → Secrets and variables → Actions) 사용. 단 정적 사이트라 빌드 후 결과물에 secret 이 노출되면 의미 없음 — NEXT_PUBLIC_* 같은 공개 키만 빌드에 주입.

런타임 secret (API key 등) 은 정적 사이트에 둘 수 없음. 별도 백엔드 (Cloudflare Workers · Netlify Functions · Replit · 직접 호스팅) 필요.

6. 한계 — 무엇을 할 수 없는가

• 서버 코드 없음 — Express · FastAPI · Spring 등은 불가. SSR 도 불가 (Static Export 만).
• DB 없음 — 모든 데이터는 빌드 시점에 정적 JSON 또는 외부 API.
• Form 처리 — <form action> 으로 외부 (Formspree · Getform · Cloudflare Forms) 위임.
• 트래픽 한도 — soft 100GB/월. 초과 시 비활성 가능 (실제 적용 사례 드뭄).
• 빌드 시간 — Action 무료 한도 (private 저장소 분당 차감). Public 저장소 무제한.

7. SSG 별 빠른 셋업

Vite (React/Vue)

// vite.config.ts
export default defineConfig({
  base: '/<repo>/',  // user site 면 '/'
  plugins: [react()],
});

Next.js (Static Export)

// next.config.ts
export default {
  output: 'export',
  basePath: '/<repo>',
  images: { unoptimized: true },
};

Astro

// astro.config.mjs
export default defineConfig({
  site: 'https://<user>.github.io',
  base: '/<repo>',
});

Hugo

# config.toml
baseURL = "https://<user>.github.io/<repo>/"

8. Replit / Vercel / Netlify 와의 비교

측면	GitHub Pages	Replit Static	Vercel	Netlify
비용 (무료 티어)	무제한 (soft)	무료 deployment 1	hobby 100GB	starter 100GB
Custom domain (무료)	✓	✗ (Core 필요)	✓	✓
HTTPS 자동	✓	✓	✓	✓
SSR · Edge	✗	일부	✓	✓
빌드 시간 (public)	무제한 (Actions)	빠름	빠름	빠름
Preview deployment	✗	✗	✓	✓
학습 곡선	보통 (Actions)	매우 낮음	낮음	낮음

오픈소스 문서 / 포트폴리오 / 블로그는 GitHub Pages 가 무료·안정·통합. 동적 기능이 필요하면 Vercel / Netlify, IDE 통합 학습 환경이면 Replit.

9. 적합한 시나리오

• 오픈소스 프로젝트 문서 (docs/ 자동 배포).
• 개인 블로그 / 포트폴리오 (Astro · Hugo · Jekyll).
• 단일 페이지 React/Vue 앱 (Vite + GH Pages).
• 회의 발표 자료 / 작은 가이드.

10. 부적합한 시나리오

• SSR / API / DB 가 필요한 풀스택 앱.
• 사용자 인증·세션·실시간 통신 (정적 페이지에서는 클라이언트 JS + 외부 백엔드 조합 필요).
• 대용량 트래픽 (100GB+).
• 빈번한 빌드 (private repo 시 Actions 시간 한도).

11. 참고 링크

• GitHub Pages 공식
• actions/deploy-pages
• Replit — IDE 통합 정적 호스팅 대안
• Fly.io — 동적 백엔드가 필요할 때