개발 2026년 1월 15일

Cloudflare Pages — git push 자동 배포 세팅

GitHub에 push하면 자동으로 빌드·배포되는 Cloudflare Pages 설정 과정.

Cloudflare Pages CI/CD 배포 Astro

왜 Cloudflare Pages인가

정적 사이트 호스팅 옵션은 많다. Vercel, Netlify, GitHub Pages, Cloudflare Pages. Karnel Labs 사이트는 Cloudflare Pages를 선택했다.

항목	Vercel	Netlify	Cloudflare Pages
무료 빌드	6,000분/월	300분/월	500회/월
대역폭	100GB	100GB	무제한
엣지 네트워크	있음	있음	있음 (300+ PoP)
Workers 연동	없음	Functions	Workers (네이티브)

결정적 차이는 무제한 대역폭과 Workers 네이티브 연동이다. Cloudflare의 다른 서비스(KV, R2, D1)와 자연스럽게 연결된다.

Cloudflare 대시보드 → Workers & Pages → Create
GitHub 저장소 연결
빌드 설정:
- Framework preset: Astro
- Build command: npm run build
- Build output directory: dist
- Root directory: karnel-website (모노레포의 경우)

빌드 시 필요한 환경 변수를 설정한다.

NODE_VERSION = 20

Astro 6은 Node.js 20+을 요구한다. Cloudflare Pages의 기본 Node 버전은 낮을 수 있으므로 명시적으로 지정한다.

Pages 프로젝트에 커스텀 도메인을 연결한다.

SSL 인증서도 자동 발급된다. 설정할 게 없다.

git push origin main
    ↓
GitHub Webhook → Cloudflare Pages
    ↓
빌드 (npm run build)
    ↓
전 세계 300+ 엣지 노드에 배포
    ↓
https://karnellabs.com 업데이트

push부터 배포 완료까지 약 30초~1분. 빌드 로그는 대시보드에서 실시간으로 확인할 수 있다.

main이 아닌 브랜치에 push하면 Preview 배포가 생성된다. 고유한 URL이 부여되어 변경사항을 미리 확인할 수 있다.

feature/blog → https://abc123.karnel-website.pages.dev

PR을 올리면 Cloudflare Bot이 Preview URL을 댓글로 남긴다. 리뷰어가 코드 없이 결과를 바로 확인할 수 있다.

Cloudflare Pages는 node_modules를 빌드 간에 캐시한다. 첫 빌드만 느리고, 이후 빌드는 패키지 설치 시간을 절약한다.

추가로 .astro/cache도 캐시되어 Astro의 콘텐츠 컬렉션 빌드가 더 빨라진다.

public/_headers와 public/_redirects 파일로 HTTP 헤더와 리다이렉트를 설정한다.

# public/_headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

# public/_redirects
/work/* /portfolio/:splat 301

서버 설정 파일을 수정할 필요 없이, 코드베이스에서 관리할 수 있다.

Cloudflare Pages는 “git push → 전 세계 배포”를 가장 간단하게 구현하는 방법이다. 무제한 대역폭, 자동 SSL, Preview 배포까지. 정적 사이트 호스팅에서 비용 걱정 없이 쓸 수 있는 최고의 옵션이다.