GitHub Pages

`docs/` 정적 사이트 자동 배포

`main` 또는 `master` 브랜치 push 시 `docs/`를 artifact로 업로드하고, GitHub Pages에 배포하도록 구성합니다.

배포 요약

1. `.github/workflows/docs-pages.yml` 커밋

2. 리포 Settings → Pages → Source: GitHub Actions

3. publish 전 `Release Gate` 워크플로우 통과 확인

4. 브랜치 푸시 후 Actions 완료 확인

5. 배포 URL에서 `docs/index.html` 확인

Workflow

name: Deploy Docs to GitHub Pages

on:
  push:
    branches: ["main", "master"]
    paths:
      - "docs/**"
      - ".github/workflows/docs-pages.yml"
  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:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs
      - id: deployment
        uses: actions/deploy-pages@v4

GitHub 저장소 설정

GitHub 저장소에서 Settings 이동
Pages 탭에서 Build and deployment 확인
Source를 GitHub Actions로 선택
Actions 탭에서 최근 배포 job 성공 여부 확인

릴리스 게이트 워크플로우: .github/workflows/release-gate.yml
로컬 동일 검증: npm run release:gate

로컬 미리보기

cd docs
python3 -m http.server 4173
# http://localhost:4173

상대 경로 링크 기준으로 작성되어 있으므로 파일 직접 열기(`file://`) 대신 로컬 서버에서 확인하세요.

자주 발생하는 이슈

문제	원인/해결
404 on refresh	정적 파일 기반 라우팅이므로 SPA rewrite가 필요 없음. 페이지 링크는 `.html` 명시 유지.
스타일 미적용	`../assets/site.css` 상대 경로 오타 확인.
페이지가 갱신되지 않음	브라우저 캐시 또는 이전 배포 artifact 확인 후 강력 새로고침.