Cloudflare Pages — Build watch paths (모노레포)

0. 목표·범위

항목	내용
목표	`main` 푸시 시 관련 경로가 바뀐 Pages 프로젝트만 빌드되도록 하여, 동시에 3개 빌드가 걸리는 빈도를 줄인다.
수단	Cloudflare 대시보드 Settings → Build → Build watch paths (공식 문서).
범위	운영·설계 문서(본 기획서). 저장소 코드 변경은 필수 아님 — 경로 목록은 팀이 합의 후 대시보드에 반영한다.
전제	Monorepos · Pages — 저장소당 Pages 프로젝트 최대 5개, Build System V2 이상.

관련: Monorepos (기본은 저장소 내 아무 파일이나 바뀌면 연결된 모든 프로젝트가 빌드됨), 배포 큐 이슈 시 cloudflare-pages-deployment-queued.md (저장소 루트 docs/error/).

동일 GitHub 저장소(Pregoi/Prego 등)에 Workers & Pages 프로젝트가 여러 개(prego-www, prego-devdoc, prego-web 등) 연결되어 있으면, 기본 설정에서는 한 번의 푸시마다 각 프로젝트가 모두 새 빌드를 받는다.
계정의 동시 빌드 슬롯이 부족하면 나머지는 Queued로 쌓인다 (Pages 요금·동시성 및 계정 플랜별 차이 참고).
Build watch paths로 “이 프로젝트의 산출물과 무관한 커밋”에서는 빌드를 스킵하면, 동시에 돌아가는 빌드 수와 대기 시간을 줄일 수 있다.

Include / Exclude
- 먼저 exclude에 걸리면 해당 경로는 무시.
- 남은 변경 파일이 include 중 하나라도 만족하면 빌드 실행.
- 아무 것도 안 맞으면 빌드 스킵 (Build watch paths).
와일드카드
- *는 경로 구분자 /를 포함해 매칭.
- 예: apps/www/*는 apps/www 아래 중첩 디렉터리까지 포함하는 패턴으로 쓸 수 있다(문서 예: docs/*).
스킵이 강제로 무시되는 경우 (매칭 없이도 빌드됨)
- 푸시에 파일 변경이 0개인 이벤트(빈 푸시 등)
- 3000개 이상 파일 변경
- 20개 이상의 커밋이 한 푸시에 포함
GitHub Checks
- 빌드가 스킵되면 해당 프로젝트에 대한 check run이 안 뜰 수 있다 (Monorepos § GitHub check runs).
한 저장소당 프로젝트 수
- 최대 5개 — 그 이상은 Cloudflare에 한도 상향 요청 (Monorepos § Limitations).

실제 Cloudflare 프로젝트 이름·Root directory·Build command는 대시보드와 apps/www/README.md 등과 반드시 대조한다. 아래는 경로 기준 설계 초안이다.

산출물: apps/www (Next.js output: 'export' → apps/www/out).
Pages Functions: 저장소 루트 functions/가 빌드 시 apps/www/functions/로 동기화됨 — www 배포에 필요.

Include 후보 (논의 후 확정)

경로 패턴	이유
`apps/www/*`	www 앱 본문·설정·e2e 등
`functions/*`	`/api/trial/*`, `/api/country` 등 동일 출처 프록시
`packages/prego-shell/*`	Header/Footer 등
`packages/prego-lottie-ui/*`	로더·공유 UI
`packages/prego-cookie-consent/`, `packages/prego-web-cookies/`	쿠키·동의 UI
`packages/prego-theme-context/*`	테마
`packages/prego-favicon/*`	파비콘 패키지
`packages/platform-trust/*`	트라이얼 게이트 등에서 사용

추가로 포함할지 검토

루트 pnpm-lock.yaml, pnpm-workspace.yaml, 루트 package.json — 한 번에 전 앱이 영향받을 수 있어, 모든 Pages가 다시 빌드되게 두는 편이 안전할 수 있다. 반대로 include를 최소화하면 lockfile만 바뀐 커밋에서 www 빌드가 스킵될 수 있어 의도치 않게 배포 누락이 난다.
권장: 초기에는 lockfile/워크스페이스 루트 변경 시 www 포함을 검토하거나, 스킵 후 수동 Retry deployment로 보완하는 운영 규칙을 둔다.

Exclude 후보

docs/* — 내부 Starlight만 바뀐 경우 www 빌드 생략(다른 프로젝트와 역할 분담).
apps/client-web/*, apps/admin-web/* — www가 직접 의존하지 않으면 제외 검토(단, 공용 패키지 변경과 커밋이 섞이면 주의).

산출물: 워크스페이스의 docs/ (prego-docs-internal — Astro Starlight). 루트 스크립트 build:docs와 동일 트리.

Include 후보

docs/*
(선택) docs만 쓰는 경우 루트 lockfile 변경 시에도 문서 빌드가 필요하면 pnpm-lock.yaml 등을 포함할지 팀 규칙으로 결정.

Exclude

apps/*, 대부분의 packages/* — 문서만 수정한 푸시에서 불필요한 재빌드를 막기 위해, 이 프로젝트의 기본 include를 docs/* 위주로 두는 것이 목적에 맞다.

저장소 내 실제 Root directory·빌드 명령에 맞춰 별도 표로 정한다.
예: apps/client-web 전용이면 apps/client-web/* + 해당 앱이 의존하는 packages/*만 include.
확정 전에는 이 기획서 표에 “미확정”으로 두고, 운영자가 대시보드 설정과 함께 본 절을 업데이트한다.

packages/prego-shell 등을 www와 다른 앱이 함께 쓰면, 그 패키지 변경 시 include에 넣은 모든 프로젝트가 빌드될 수 있다 — 이는 의도된 동작이다 (실제로 양쪽 산출물이 바뀌므로).
한 패키지 변경으로 세 프로젝트가 모두 include에 걸리지 않게 하려면, 패키지를 앱별로 쪼개거나 include를 더 세분화해야 하며, 관리 비용이 늘어난다.

Build System V2 사용 여부 확인 (Pages → Settings → Build).
프로젝트별로 현재 Root / Build command / Output 기록.
위 표를 바탕으로 include / exclude 초안을 팀 리뷰.
Staging/프리뷰 브랜치에서 먼저 적용해 보거나, 프로덕션에서 한 프로젝트씩 적용.
테스트 시나리오:
- docs/만 변경 → devdoc만 빌드(또는 www/web 스킵) 확인.
- apps/www/만 변경 → www만 해당 확인.
- packages/prego-shell만 변경 → www(+ shell 쓰는 다른 앱) 빌드 확인.
문서화: 확정된 경로를 본 파일에 반영하고, apps/www/README.md 배포 절에 “Build watch paths 요약” 링크를 추가할지 선택.

리스크	완화
include 누락으로 필요한 배포가 스킵	lockfile·공용 설정 변경 시 포함 여부 명시; 수동 Retry; PR에서 경로 리뷰
거대 커밋(20+ commits / 3000+ files) 시 전부 빌드	드물게 발생 — 릴리스 프로세스에서 커밋 수 조절 또는 수동 배포
팀원 혼동(GitHub check 안 뜸)	스킵이 정상임을 문서화