Cloudflare Pages 배포 운영

이 위키는 GitHub의 kjm081025-maker/project-wiki 저장소와 Cloudflare Pages의 project-wiki 프로젝트를 연결해 배포한다.

자동 배포 흐름

1. 작업자는 별도 branch에서 Markdown을 수정한다.
2. Pull Request를 만들면 GitHub Actions가 mkdocs build --strict를 실행한다.
3. Cloudflare Pages가 같은 branch의 Preview 배포를 만든다.
4. 검토자는 Preview URL에서 탐색, 검색, 링크와 문서 표시를 확인한다.
5. Pull Request를 main에 병합하면 Production이 자동 갱신된다.

빌드 설정

항목	값
Production branch	main
Build command	python -m pip install -r requirements.txt && python -m mkdocs build --strict
Build output directory	site
Root directory	저장소 루트
Python	.python-version의 3.12

장애 확인 순서

1. Pull Request의 GitHub Actions Validate documentation 결과를 확인한다.
2. 실패했다면 Actions 로그에서 MkDocs 오류와 끊어진 내부 링크를 먼저 고친다.
3. Actions는 성공하고 Pages만 실패했다면 Cloudflare Pages의 해당 배포 로그를 확인한다.
4. Production 장애 시 마지막 성공 배포와 현재 main commit을 비교한다.

접근과 권한

• GitHub 원본 저장소는 비공개이며 초대된 공동 작업자만 수정하거나 새 페이지를 만들 수 있다.
• Cloudflare GitHub 앱은 이 저장소 한 곳에만 접근하도록 제한한다.
• pages.dev Production 사이트의 열람 접근 제한은 별도 Cloudflare Access 정책으로 관리한다.
• 개인 GitHub 계정, 토큰 또는 AI 도구 자격 증명을 공동 사용하지 않는다.

사용자 설정 도메인

Cloudflare 계정에 관리 중인 Zone이 생긴 뒤 wiki.<도메인>을 Pages 프로젝트에 연결한다. 기존 DNS 레코드를 먼저 확인하고 충돌이 없을 때만 추가한다.