Preview Deployments

Cloudflare Pages의 프리뷰 배포 기능을 사용하면 변경 사항을 프로덕션에 반영하기 전에 스테이징 환경에서 미리 확인할 수 있습니다.

프리뷰 배포란?

프리뷰 배포는 프로덕션 브랜치가 아닌 다른 브랜치에 커밋할 때 자동으로 생성되는 임시 배포입니다. 각 Pull Request마다 고유한 프리뷰 URL이 생성되어 변경 사항을 팀원들과 공유하고 검토할 수 있습니다.

주요 특징

Pull Request 생성 시 자동으로 프리뷰 배포 생성
새 커밋 푸시 시 프리뷰 자동 업데이트
프로덕션 환경과 완전히 분리
무기한 접근 가능

프리뷰 URL 구조

해시 기반 URL

각 커밋마다 고유한 해시 기반 URL이 생성됩니다:

<hash>.<project>.pages.dev

예시:

373f31e2.my-project.pages.dev
a1b2c3d4.my-project.pages.dev

브랜치 별칭 (Branch Alias)

브랜치 이름을 기반으로 한 별칭 URL도 자동 생성됩니다. 이 URL은 해당 브랜치의 최신 커밋을 항상 가리킵니다:

<branch-name>.<project>.pages.dev

예시:

브랜치 이름	별칭 URL
`development`	`development.my-project.pages.dev`
`staging`	`staging.my-project.pages.dev`
`feature/login`	`feature-login.my-project.pages.dev`
`fix/api-bug`	`fix-api-bug.my-project.pages.dev`

참고: 브랜치 이름의 영숫자가 아닌 문자(/, _ 등)는 하이픈(-)으로 변환됩니다.

프로덕션과의 분리

프리뷰 배포는 다음에 영향을 주지 않습니다:

메인 *.pages.dev 도메인
커스텀 도메인
프로덕션 환경 설정

프리뷰 URL과 브랜치 별칭만 업데이트됩니다.

접근 제어

기본 설정

기본적으로 프리뷰 배포는 공개입니다. 누구나 프리뷰 URL에 접근할 수 있습니다.

접근 제한 설정

프리뷰 배포에 접근 제한을 설정하려면:

Cloudflare 대시보드에서 Pages 프로젝트 선택
Settings > General 이동
Enable access policy 활성화
Cloudflare Access 정책 설정

Cloudflare Access 정책 예시

# 팀 멤버만 접근 허용
Allow: team@company.com

# 특정 이메일 도메인만 허용
Allow: *@company.com

# GitHub 인증 사용
Allow: GitHub organization members

참고: 접근 제어는 프리뷰 URL과 브랜치 별칭에만 적용됩니다. 프로덕션 도메인에는 영향을 주지 않습니다.

검색 엔진 보호

Cloudflare는 모든 프리뷰 배포에 자동으로 다음 HTTP 헤더를 추가합니다:

X-Robots-Tag: noindex

이를 통해:

검색 엔진이 프리뷰 페이지를 인덱싱하지 않음
중복 콘텐츠로 인한 SEO 영향 방지
미완성 콘텐츠가 검색 결과에 노출되지 않음

프리뷰 배포 활용

Pull Request 리뷰

graph LR
    A[PR 생성] --> B[프리뷰 배포]
    B --> C[팀 리뷰]
    C --> D[피드백 반영]
    D --> B
    C --> E[PR 머지]
    E --> F[프로덕션 배포]

스테이징 환경

staging 브랜치를 사용하여 영구적인 스테이징 환경을 구성할 수 있습니다:

staging.my-project.pages.dev

이 URL은 staging 브랜치의 최신 커밋을 항상 반영합니다.

QA 테스트

QA 팀에게 브랜치 별칭 URL을 공유하여 테스트를 진행할 수 있습니다:

기능 브랜치 생성: feature/new-checkout
프리뷰 URL 공유: feature-new-checkout.my-project.pages.dev
QA 팀 테스트 진행
피드백 반영 후 커밋
프리뷰 자동 업데이트

프리뷰 배포 설정

Branch Build Controls와 연동

Branch Build Controls를 사용하여 프리뷰 배포할 브랜치를 제어할 수 있습니다:

# Include branches (프리뷰 배포할 브랜치)
staging
develop
feat/*
fix/*

# Exclude branches (프리뷰 배포 제외)
dependabot/*
renovate/*

환경 변수

프리뷰 배포에서는 Preview 환경 변수가 사용됩니다:

환경	환경 변수
Production	Production 환경 변수
Preview	Preview 환경 변수

대시보드에서 Settings > Environment variables에서 환경별로 다른 값을 설정할 수 있습니다.

GitHub/GitLab 통합

Pull Request 코멘트

Git 연동 시 PR에 자동으로 프리뷰 배포 링크가 코멘트로 추가됩니다:

✅ Deploy Preview for my-project ready!

🔗 Preview URL: https://abc123.my-project.pages.dev
📦 Branch: feature/new-feature
⏱️ Built in 45s

배포 상태

PR의 Checks 섹션에서 빌드 상태를 확인할 수 있습니다:

✅ Success: 프리뷰 배포 완료
❌ Failed: 빌드 실패
🟡 Pending: 빌드 진행 중

제한 사항

프리뷰 배포 수

프리뷰 배포는 무기한 유지됩니다
오래된 배포는 자동 삭제되지 않음
필요 시 대시보드에서 수동 삭제 가능

리소스 제한

프리뷰 배포도 프로덕션과 동일한 리소스 제한이 적용됩니다:

Functions 실행 시간
대역폭 제한
요청 수 제한

바인딩

프리뷰 환경에서 사용할 별도의 바인딩(KV, D1, R2 등)을 설정할 수 있습니다:

[[kv_namespaces]]
binding = "MY_KV"
id = "production-kv-id"

[env.preview]
[[env.preview.kv_namespaces]]
binding = "MY_KV"
id = "preview-kv-id"

베스트 프랙티스

1. 브랜치 명명 규칙

일관된 브랜치 명명으로 프리뷰 URL을 예측 가능하게 만듭니다:

# Good
feature/user-auth
fix/login-bug
chore/update-deps

# Bad (특수문자 많음)
feature/user_auth@v2
fix/login#123

2. 접근 제어 활성화

민감한 프로젝트에서는 Cloudflare Access를 활성화하여 프리뷰 접근을 제한합니다.

3. 환경 변수 분리

프리뷰와 프로덕션에서 다른 API 엔드포인트나 설정을 사용하도록 환경 변수를 분리합니다:

# Production
API_URL=https://api.example.com

# Preview
API_URL=https://staging-api.example.com

4. 브랜치 빌드 제어

불필요한 브랜치(dependabot, renovate 등)의 프리뷰 배포를 비활성화하여 리소스를 절약합니다.

출처: Cloudflare Pages - Preview Deployments