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

1. 비공개 저장소에 예제 올리기#

Workers starter ZIP 다운로드

이 ZIP은 Workers에 올릴 정적 사이트와 배포 설정을 한 번에 준비한 예제다. 압축을 풀면 starter 폴더가 나오며, starter 폴더 자체가 아니라 그 안의 내용만 GitHub 저장소 최상위에 올린다.

1. GitHub 새 저장소 만들기를 연다.
2. Repository name은 hello-worker-site, Choose visibility는 Private로 선택한다.
3. README·gitignore·license 추가 옵션은 끄고 Create repository를 누른다.
4. 위의 Workers starter ZIP을 풀고 starter 폴더를 연다. GitHub의 uploading an existing file을 누르고, starter 안의 파일과 public 폴더를 업로드 영역으로 끌어 넣는다. 파일이 있는 저장소에서는 Add file → Upload files를 사용한다.
5. Commit changes로 저장한다. 기본 브랜치가 main인지 확인한다.

ZIP 파일 자체나 starter 폴더 전체를 올리지 않는다. 저장소를 열었을 때 public과 wrangler.jsonc가 바로 보여야 한다.

1
hello-worker-site/
2
├─ public/
3
│  ├─ index.html
4
│  ├─ style.css
5
│  └─ 404.html
6
├─ wrangler.jsonc
7
├─ package.json
8
├─ package-lock.json
9
└─ .gitignore

public/index.html이 첫 화면이고, public/style.css가 디자인을 정한다. public에는 공개할 파일만 넣는다. .gitignore가 탐색기에 보이지 않으면 보기 → 표시 → 숨긴 항목을 켠다.

예제의 wrangler.jsonc는 다음과 같다. Worker 이름과 공개 폴더를 지정한 설정이다. 그대로 사용하면 추가 수정 없이 다음 단계로 갈 수 있다.

1
{
2
  "$schema": "node_modules/wrangler/config-schema.json",
3
  "name": "hello-worker-site",
4
  "compatibility_date": "2026-09-20",
5
  "workers_dev": true,
6
  "assets": {
7
    "directory": "./public",
8
    "not_found_handling": "404-page",
9
    "html_handling": "auto-trailing-slash"
10
  }
11
}

package.json과 package-lock.json에는 배포 도구 Wrangler 4.135.0이 고정되어 있다. 두 파일도 함께 올린다. 실제 실습의 최초 파일 업로드는 로컬 Git의 commit·push로 수행했으며, 위 화면은 그 결과다. 브라우저 업로드는 같은 파일 구성을 만드는 방법이다. GitHub 파일 업로드 문서

2. 새 Worker 만들고 GitHub 연결하기#

이 단계에서 새 Worker가 만들어진다. 아래 순서대로 진행하고 마지막에 Deploy를 누르면 Worker 생성과 GitHub 연결, 첫 배포가 함께 진행된다.

1. Cloudflare에 로그인하고 사용할 계정을 연다.
2. 왼쪽 메뉴에서 Compute → Workers & Pages를 누른다.
3. Create application → Continue with GitHub를 누른다.
4. 본인 GitHub 계정과 hello-worker-site 저장소를 선택하고 Next를 누른다.

이미 이 실습을 완료한 계정에는 hello-worker-site Worker가 있다. 기존 사이트를 수정할 때는 새로 만들지 않고 Workers & Pages → hello-worker-site를 열거나, 아래 4단계대로 GitHub 파일을 수정한다.

저장소가 목록에 없을 때는 GitHub account → Add GitHub account를 누른다. GitHub의 Cloudflare Workers and Pages 설정에서 Only select repositories → Select repositories로 hello-worker-site를 추가하고 Save한다. 기존에 선택된 저장소는 그대로 둔다. Confirm access가 뜨면 GitHub 본인 인증을 마친다. Cloudflare로 돌아온 뒤에도 목록이 그대로면 새로고침하고 연결 화면을 다시 연다.

배포 화면에는 아래 값을 입력한다.

이 예제는 HTML·CSS 파일을 그대로 배포하므로 Build command가 없다. Project name과 wrangler.jsonc의 name은 같아야 한다. 토큰은 Cloudflare 빌드가 배포에 사용한다. 생성 화면에서 권한을 확인하고 진행한다. 이 실습에서는 Cloudflare가 표시한 기본 권한으로 생성했으며, 토큰 값을 GitHub 파일이나 Secrets에 복사하는 단계는 없다. Workers Builds 문서

Deploy를 누르면 hello-worker-site라는 새 Worker가 생성되고 첫 배포가 시작된다. 완료 후 Worker의 Deployments → Recent builds에 성공 표시가 있는지 확인하고, 기본 주소를 연다. 첫 배포에서는 “배포 성공!” 문구가 나와야 한다. 빌드가 실패했다면 해당 빌드를 눌러 로그의 오류를 확인한다.

3. 내 도메인 연결하기#

1. 방금 만든 Worker hello-worker-site의 Domains 탭을 연다.
2. Add Domain을 누른다.
3. Search domains에서 루트 도메인 v3s9er.com을 검색하고 선택한다. 이 검색칸에는 guide.v3s9er.com이 아니라 Cloudflare에 등록된 루트 도메인을 넣는다.
4. 다음 화면의 **Subdomain (optional)**에 guide를 입력한다.
5. Add domain을 누른다.

연결이 끝나면 목록에 guide.v3s9er.com이 표시된다. Cloudflare가 이 Custom Domain의 DNS와 인증서를 구성하므로 별도 CNAME을 먼저 추가하지 않는다. Custom Domains 문서

https://guide.v3s9er.com을 열어 기본 주소와 같은 페이지가 보이는지 확인한다. 다른 도메인으로 실습할 때는 비어 있는 서브도메인을 사용한다. Subdomain을 비워 두면 루트 도메인에 연결되므로 이 실습에서는 guide를 입력한다.

4. 수정 후 자동 배포 확인하기#

1. GitHub 저장소에서 **public → index.html → 연필 아이콘(Edit this file)**을 누른다.
2. <h1>배포 성공!</h1>을 <h1>자동 배포 확인 완료!</h1>로 바꾼다.
3. **Commit changes…**를 누른다. 메시지는 Verify automatic deployment로 입력한다.
4. Commit directly to the main branch를 선택하고 Commit changes를 누른다.

Cloudflare의 Deployments → Recent builds에서 새 커밋의 빌드가 시작된다. 별도로 Deploy를 누르지 않는다. 성공 표시가 나온 뒤 사용자 도메인을 새로고침한다. **“자동 배포 확인 완료!”**로 바뀌면 GitHub 연결부터 실제 서비스 반영까지 완료된 것이다.

이후에는 public 안의 HTML·CSS·이미지를 수정하고 main에 커밋하면 된다. 예제의 wrangler.jsonc에는 routes를 따로 지정하지 않았으며, 이번 자동 재배포 후에도 대시보드에서 연결한 도메인이 유지되는 것을 확인했다.

문제가 생기면 아래 항목을 확인한다.