Pages Git Integration

Cloudflare Pages는 GitHub 및 GitLab과 연동하여 코드를 푸시할 때마다 자동으로 빌드하고 배포합니다.

개요

Git 연동의 주요 기능:

• 자동 배포: 커밋 푸시 시 자동 빌드 및 배포
• Preview 배포: PR/MR에 대한 미리보기 환경 자동 생성
• 커밋 상태 연동: Git 제공자에서 빌드 상태 확인 가능

주의: Git 연동으로 배포를 시작하면 나중에 Direct Upload 방식으로 변경할 수 없습니다. 단, 자동 배포를 비활성화하고 Wrangler로 수동 배포하는 것은 가능합니다.

Git 제공자 연결

설정 단계

1. Cloudflare 대시보드에서 Workers & Pages로 이동
2. Create application > Pages > Connect to Git 선택
3. Git 제공자(GitHub 또는 GitLab)로 인증
4. 저장소 선택 (비공개/공개 모두 지원)
5. Install & Authorize 후 Begin setup 클릭

GitHub 연결

GitHub 계정 또는 조직의 저장소를 연결할 수 있습니다.

1. GitHub으로 인증
2. Cloudflare Pages 앱 설치 권한 부여
3. 접근 권한 설정:
   • 모든 저장소 접근 허용
   • 또는 특정 저장소만 선택

설치된 앱은 GitHub Applications 페이지에서 확인할 수 있습니다.

조직 저장소의 경우 Switch settings context를 선택하여 조직 설정에 접근합니다.

GitLab 연결

GitLab 연동 시 주의사항:

• 저장소에 대해 Maintainer 역할 이상이 필요합니다
• GitLab으로 로그인하면 계정의 모든 저장소에 대한 접근 권한이 부여됩니다
• 같은 계정의 다른 멤버도 해당 저장소를 배포할 수 있습니다

설치된 앱은 GitLab Authorized Applications 페이지에서 확인할 수 있습니다.

빌드 설정

필수 설정

프레임워크 프리셋

Cloudflare Pages는 주요 프레임워크에 대한 프리셋을 제공합니다:

프레임워크 없이도 정적 파일을 배포할 수 있습니다. 빌드 명령어를 비워두면 됩니다.

고급 설정

Root Directory

모노레포나 비표준 구조에서 빌드 경로를 지정합니다:

my-monorepo/
├── packages/
│   ├── frontend/    ← Root directory: packages/frontend
│   └── backend/
└── package.json

Environment Variables

빌드 시 사용할 환경 변수를 설정합니다:

Preview 배포

동작 방식

• Production branch 외의 모든 브랜치는 Preview 배포를 생성합니다
• 각 커밋마다 고유한 Preview URL이 생성됩니다
• Pull Request에 Preview 배포 링크가 자동으로 댓글로 추가됩니다

Preview URL 형식

https://<commit-hash>.<project-name>.pages.dev

예시:

• https://abc1234.my-project.pages.dev
• https://feature-login.my-project.pages.dev

Branch 배포 설정

특정 브랜치에 대해서만 Preview 배포를 활성화할 수 있습니다:

Settings > Builds & deployments > Branch deployments

Preview 환경 변수

Preview와 Production에서 다른 환경 변수를 사용할 수 있습니다:

Settings > Environment variables

배포 관리

대시보드에서 확인

배포 후 대시보드에서 확인할 수 있는 정보:

• 현재 배포 상태 (성공/실패/진행중)
• Production URL 및 연결된 커밋
• 배포 이력

배포 재시도

실패한 배포는 대시보드에서 Retry deployment를 클릭하여 재시도할 수 있습니다.

롤백

이전 배포로 롤백하려면:

1. Deployments 탭에서 이전 배포 선택
2. Manage deployment > Rollback to this deployment

GitHub Actions 연동

Git 연동 대신 GitHub Actions를 사용하여 더 세밀한 제어가 가능합니다:

name: Deploy to Cloudflare Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy dist --project-name=my-project

필요한 Secrets

GitHub repository settings에서 다음 secrets를 설정합니다:

API 토큰 생성: Cloudflare Dashboard > My Profile > API Tokens > Create Token

필요한 권한:

• Cloudflare Pages:Edit
• Account:Read

프로젝트 설정 변경

설정 수정

Settings 탭에서 수정 가능한 항목:

• 프로젝트 이름
• Git 연결 설정
• 빌드 명령어
• 빌드 출력 디렉토리
• 환경 변수

프로젝트 삭제

1. Settings > Delete project
2. 프로젝트 이름 입력하여 확인

주의: 커스텀 도메인을 사용 중인 경우, 프로젝트 삭제 전에 CNAME 레코드를 먼저 제거하세요. 그렇지 않으면 고아 DNS 엔트리가 남을 수 있습니다.

Wrangler 설정 (선택사항)

Git 연동과 함께 wrangler.toml을 사용하여 환경별 설정을 관리할 수 있습니다:

name = "my-pages-project"
compatibility_date = "2025-03-25"

[vars]
API_HOST = "api.example.com"
ENVIRONMENT = "development"

[env.staging]
[env.staging.vars]
API_HOST = "staging-api.example.com"
ENVIRONMENT = "staging"

[env.production]
[env.production.vars]
API_HOST = "production-api.example.com"
ENVIRONMENT = "production"

Preview URL 활성화

Workers에서 Pages와 유사한 Preview URL을 활성화하려면:

name = "my-worker"
compatibility_date = "2025-04-01"
main = "./worker/index.ts"
preview_urls = true

[assets]
directory = "./dist/client/"

제한사항

자주 사용하는 빌드 명령어

# Node.js 버전 지정
NODE_VERSION=18 npm run build

# npm 플래그 추가
NPM_FLAGS=--legacy-peer-deps npm install && npm run build

# 환경 변수와 함께 빌드
API_URL=https://api.example.com npm run build

Git 연동 관리

Git 연동 설정 후 연동을 관리하고 문제를 해결하는 방법입니다.

연동 상태 확인

Settings > Builds > Git Repository에서 Manage 클릭

여기서 확인 가능한 정보:

• 연결된 Git 제공자
• 저장소 URL
• 권한 상태

지원되는 Git 제공자

Self-hosted Git이나 Bitbucket을 사용하는 경우, Direct Upload와 CI/CD 도구(GitHub Actions, GitLab CI 등)를 함께 사용하세요.

설치 확인

Git 연동 앱이 제대로 설치되었는지 확인:

• GitHub: GitHub Applications > Cloudflare Pages 확인
• GitLab: GitLab Authorized Applications > Cloudflare Pages 확인

자동 배포 일시 중지

자동 배포를 일시적으로 중지하고 싶을 때 사용합니다.

Production 브랜치 배포 중지

1. Settings > Builds & deployments 이동
2. Configure Production deployments 클릭
3. Enable automatic production branch deployments 체크 해제
4. Save 클릭

Preview 브랜치 배포 중지

1. Settings > Builds & deployments 이동
2. Configure Preview deployments 클릭
3. None (Disable automatic branch deployments) 선택
4. Save 클릭

배포 중지 후 수동 배포

자동 배포를 중지한 후에도 Wrangler를 사용하여 수동으로 배포할 수 있습니다:

# 빌드 후 수동 배포
npm run build
npx wrangler pages deploy dist

Git 연동 재설치

연동에 문제가 있을 때 재설치하여 해결할 수 있습니다.

재설치가 필요한 경우

• 저장소 접근 권한 오류
• 빌드 트리거가 작동하지 않음
• 조직 권한 변경 후 동기화 필요

GitHub 재설치 방법

1. GitHub Applications로 이동
2. Cloudflare Pages 선택
3. Configure 클릭
4. 페이지 하단에서 Uninstall 클릭
5. Cloudflare 대시보드에서 프로젝트 선택
6. Settings > Builds > Manage 클릭
7. Reinstall Git integration 선택
8. 다시 권한 부여

GitLab 재설치 방법

1. GitLab Authorized Applications로 이동
2. Cloudflare Pages 찾기
3. Revoke 클릭
4. Cloudflare 대시보드에서 재연결

조직 저장소 접근

GitHub 조직

GitHub 조직의 저장소를 사용하려면:

1. 조직의 Owner 또는 Admin 권한 필요
2. 연결 시 Switch settings context로 조직 선택
3. 조직에 Cloudflare Pages 앱 설치 승인

GitLab 그룹

GitLab 그룹 프로젝트 사용 시:

1. 해당 프로젝트의 Maintainer 역할 이상 필요
2. 그룹 프로젝트 선택 시 같은 계정의 다른 멤버도 해당 프로젝트 배포 가능

문제 해결

”Repository not found” 오류

원인: 저장소 접근 권한 없음

해결:

1. Git 제공자에서 Cloudflare Pages 앱 권한 확인
2. 저장소가 앱에 접근 허용되어 있는지 확인
3. 필요시 Git 연동 재설치

”Build not triggered” 오류

원인: Webhook 전달 실패 또는 자동 배포 비활성화

해결:

1. 자동 배포가 활성화되어 있는지 확인
2. 브랜치가 배포 대상에 포함되어 있는지 확인
3. Git 연동 재설치 시도

”Authorization expired” 오류

원인: OAuth 토큰 만료

해결:

1. Cloudflare 대시보드에서 Manage 클릭
2. Reinstall Git integration 선택
3. 다시 인증

출처:

• Cloudflare Pages - Git Integration
• Cloudflare Pages - Git Integration Configuration