ADR-0010: Cloudflare Pages 위키 배포

문제#

GitHub 저장소는 raw 원본과 내부 조사 문서를 포함해 비공개로 유지해야 한다. 현재 GitHub 요금제에서는 비공개 저장소의 Pages 활성화가 지원되지 않아 기존 배포 워크플로가 HTML 빌드 뒤 실패했다. 원본 저장소를 공개하지 않고 생성된 HTML만 공유할 배포 경로가 필요하다.

근거와 한계#

Cloudflare Pages Direct Upload는 미리 빌드한 폴더를 Wrangler로 업로드하고 pages.dev 주소에서 제공한다. ^[1] 배포 대상 폴더를 dist/로 제한하면 raw와 wiki 원본은 업로드되지 않는다.

Direct Upload 프로젝트는 같은 프로젝트에서 Git integration으로 전환할 수 없다. 자동 배포에는 별도 API 토큰과 계정 ID가 필요하므로 현재 단계에서는 로컬 OAuth 배포를 사용한다.

wrangler.toml에 Pages 출력 경로를 선언하면 저장소의 설정이 프로젝트 설정의 기준이 된다. _headers는 정적 응답에 보안 헤더를 적용할 수 있다. ^[2] ^[3] 검색 로봇의 색인을 제한할 수 있지만 이는 인증이나 접근 제어를 대신하지 않는다.

결정#

공유 위키는 after-work-dating-wiki Cloudflare Pages 프로젝트에 배포한다.
공개 주소는 https://after-work-dating-wiki.pages.dev/를 사용한다.
npm --prefix tools/wiki-publisher run deploy:cloudflare가 검증, 빌드와 배포를 수행한다.
tools/wiki-publisher/wrangler.toml에서 프로젝트 이름과 dist/ 경로를 한 번만 관리한다.
배포 뒤 공개 홈, 중첩 문서, CSS, 보안 헤더와 404를 실제 주소에서 자동 확인한다.
정적 응답에는 CSP, 프레이밍 방지, 권한 제한과 noindex 헤더를 적용한다.
GitHub Actions는 위키 검증만 수행하고 배포 토큰을 저장하지 않는다.
배포 대상은 tools/wiki-publisher/dist/로 제한한다.
Cloudflare OAuth 자격 증명과 API 토큰은 저장소에 기록하지 않는다.
공개 주소는 로그인 없이 접근 가능하다. 기밀성이 필요해지면 별도 접근 제어를 결정한다.
장애 시 직전의 성공한 프로덕션 배포로 롤백한다. 프리뷰 배포는 롤백 대상으로 쓰지 않는다. ^[4]

선택하지 않은 방식#

현재 GitHub 저장소 공개 전환: raw 원본까지 공개되므로 선택하지 않았다.
비공개 저장소의 GitHub Pages: 현재 계정 요금제에서 활성화되지 않아 선택하지 않았다.
별도 공개 GitHub 배포 저장소: 원본과 생성물 저장소를 추가로 동기화해야 해 선택하지 않았다.
Cloudflare API 토큰 기반 자동 배포: 토큰 수명과 권한 정책을 정하기 전이라 보류했다.

재검토 조건#

팀이 수동 배포 지연을 반복해서 겪어 자동 배포의 이점이 토큰 관리 위험보다 커진다.
사용자 인증이 필요한 비공개 위키로 접근 범위를 제한해야 한다.
사용자용 랜딩페이지가 생겨 위키와 별도 도메인과 배포 정책이 필요해진다.

운영 절차: docs/playbooks/deploy-wiki.md

ADR-0010: Cloudflare Pages 위키 배포

근거 4

연결된 문서 2

문제#

근거와 한계#

결정#

선택하지 않은 방식#

재검토 조건#