GitHub 비공개 저장소로 Cloudflare Pages에 사이트 배포하기#

1. 비공개 GitHub 저장소 준비하기#

GitHub·Cloudflare 계정과 Cloudflare에서 활성화된 본인 도메인이 필요하다. 이 실습의 도메인은 이미 Cloudflare에서 DNS를 관리하고 있다.

Pages starter ZIP 다운로드

이 ZIP은 Pages 빌드에 필요한 원본 파일과 최소 설정을 모아 둔 예제다. 압축을 풀면 starter 폴더가 나오며, starter 폴더 자체가 아니라 그 안의 내용만 GitHub 저장소 최상위에 올린다.

1. GitHub 새 저장소 만들기를 연다.
2. Repository name에 hello-pages-site를 입력하고 Private를 선택한다.
3. README·gitignore·license 자동 추가 옵션을 끄고 Create repository를 누른다.
4. 위의 Pages starter ZIP을 풀고 starter 폴더 안의 파일과 src 폴더를 저장소에 올린다. 빈 저장소에서는 uploading an existing file, 파일이 있는 저장소에서는 Add file → Upload files를 사용한다.
5. Commit changes로 저장하고 main 브랜치가 생겼는지 확인한다.

ZIP 자체나 starter 폴더 전체를 올리지 않는다. 저장소 첫 화면에 package.json, build.mjs, src가 바로 보여야 한다.

1
hello-pages-site/
2
├─ src/
3
│  ├─ index.html
4
│  ├─ style.css
5
│  └─ 404.html
6
├─ build.mjs
7
├─ package.json
8
├─ pnpm-lock.yaml
9
├─ README.md
10
└─ .gitignore

src/index.html은 첫 화면, src/style.css는 디자인, src/404.html은 없는 주소에 표시할 화면이다. build.mjs는 이 세 파일을 dist로 복사한다. 빌드 결과인 dist와 node_modules는 업로드하지 않는다.

1
{
2
  "name": "hello-pages-site",
3
  "private": true,
4
  "version": "1.0.0",
5
  "type": "module",
6
  "packageManager": "pnpm@10.11.0",
7
  "scripts": { "build": "node build.mjs" }
8
}

이 package.json과 build.mjs가 있어야 다음 단계의 pnpm build가 동작한다. 제공 파일을 그대로 사용하면 된다. 실제 실습에서는 로컬 Git의 commit·push로 처음 업로드했다. 위 브라우저 업로드 절차는 같은 파일 구성을 만드는 방법이다. GitHub 파일 업로드 문서

2. Pages 프로젝트 만들고 GitHub 연결하기#

1. Cloudflare에서 Compute → Workers & Pages → Create application을 연다.
2. 생성 화면 아래의 Continue to Pages를 누른다.
3. Import an existing Git repository → Get started를 누른다.
4. GitHub 계정에서 hello-pages-site를 선택하고 Begin setup을 누른다.

저장소가 목록에 없으면 화면의 GitHub 설치·저장소 권한 설정 링크를 연다. GitHub의 Cloudflare Workers and Pages → Repository access → Only select repositories에서 새 저장소를 추가하고 Save한다. 기존에 선택된 저장소는 유지한다. Cloudflare 화면을 새로고침하면 새 저장소를 선택할 수 있다. 이번 실습도 기존 연결에 hello-pages-site를 추가했다.

처음 연결하는 계정은 GitHub 연결 화면에서 사용할 계정과 저장소를 선택해 설치를 완료한다. 비공개 저장소도 Cloudflare GitHub 앱에 해당 저장소 접근 권한이 있어야 목록에 표시된다.

3. 빌드값 입력하고 첫 배포하기#

Set up builds and deployments에서 아래 값으로 설정한다.

Save and Deploy를 누르면 Pages 프로젝트 생성과 첫 배포가 진행된다. 완료 후 Continue to project를 누른다. Deployments에서 초록색 성공 표시를 확인하고 hello-pages-site.pages.dev를 열어 **Pages 배포 성공!**이 나오는지 확인한다.

실제 첫 배포에서 pnpm install 뒤 빌드가 실행됐고 기본 주소가 HTTP 200으로 응답했다. 이 예제는 Pages 화면에 빌드 설정을 저장했으며 Wrangler 설정 파일이나 별도 Worker를 만들지 않았다. Git 연결 및 빌드 입력 항목은 Cloudflare Git integration 문서에서도 확인할 수 있다.

4. 내 도메인 연결하기#

1. Pages 프로젝트에서 Custom domains → Set up a custom domain을 누른다.
2. 사용할 주소를 입력한다. 이번 실습은 pages-guide.v3s9er.com을 사용했다.
3. Continue를 누르고 새 DNS 레코드 내용을 확인한다.
4. 아래처럼 대상이 본인 Pages 기본 주소인지 확인한 후 Activate domain을 누른다.

이 계정에서는 Cloudflare가 새 CNAME을 추가했다. Verifying 상태이면 Complete DNS setup → Check DNS records로 재확인할 수 있다. 활성화 후 https://pages-guide.v3s9er.com/을 열어 사이트가 나오는지 확인한다. DNS·인증서 반영에는 시간이 걸릴 수 있다.

실제 최종 화면에서 Active / SSL enabled를 확인했다.

DNS에 CNAME만 직접 추가하고 끝내지 않는다. 먼저 Pages의 Custom domains에 주소를 등록해야 한다. 이 절차와 Cloudflare 관리 도메인의 자동 CNAME 추가는 Cloudflare Custom domains 문서에 설명되어 있다.

5. 파일 수정으로 자동 배포 확인하기#

1. GitHub 저장소에서 src → index.html을 연다.
2. 편집 버튼을 눌러 제목을 아래처럼 바꾼다.
3. Commit changes에서 main에 변경을 저장한다.
4. Cloudflare의 Deployments에서 새 커밋 배포가 성공할 때까지 기다린다.
5. 연결 도메인을 새로고침하고 바뀐 문구를 확인한다.

변경 전:

1
<h1>Pages 배포 성공!</h1>

변경 후:

1
<h1>Pages 자동 배포 확인 완료!</h1>

실제 검증에서는 같은 수정을 로컬에서 commit한 뒤 main으로 push했다. Cloudflare에서 배포 버튼을 다시 누르지 않아도 새 배포가 생성됐고, 기본 주소와 연결 도메인 모두 변경된 제목을 반환했다.

막힐 때 확인할 항목#