GitHub Pages — 저장소를 정적 사이트로
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 — 동적 백엔드가 필요할 때