결론부터 말하면, Cloudflare Workers Builds는 Worker 프로젝트를 GitHub 또는 GitLab 저장소와 연결해 커밋이 들어올 때 빌드와 배포를 자동으로 실행하는 흐름입니다. 처음 설정할 때는 “어느 브랜치를 감시할지”, “빌드 명령이 필요한지”, “배포 명령을 무엇으로 둘지”, “프리뷰 빌드를 어디까지 허용할지”를 먼저 정해야 합니다. 이 네 가지를 정하지 않고 연결부터 하면, 나중에 원치 않는 브랜치가 배포되거나 빌드 로그만 보고 원인을 찾느라 시간이 길어질 수 있습니다.
요약: Workers Builds는 저장소 연결 → 브랜치 선택 → 빌드 명령 확인 → 배포 명령 확인 → 프리뷰/프로덕션 분리 순서로 잡으면 안전합니다. Cloudflare 공식 문서는 Git 연동, 구성 항목, CI/CD 흐름을 기준으로 안내하므로 실제 화면 이름과 옵션은 계정 권한, 플랜, 제품 업데이트에 따라 달라질 수 있습니다.
1. Cloudflare Workers Builds가 필요한 상황
Cloudflare Workers를 대시보드에서 직접 수정하는 방식은 빠르게 테스트할 때 편합니다. 하지만 팀원이 늘거나 코드 리뷰를 거쳐야 하거나, 로컬에서 프레임워크를 빌드한 뒤 배포해야 한다면 Git 중심 흐름이 더 관리하기 쉽습니다. Workers Builds는 이런 상황에서 저장소의 변경 사항을 Cloudflare 쪽 빌드·배포 흐름으로 이어 주는 기능입니다. 공식 설명 기준으로는 Git과 통합해 변경 사항을 push했을 때 Worker를 자동 빌드하고 배포하는 목적에 맞춰져 있습니다.
특히 API 프록시, 간단한 백엔드 라우터, Edge 함수, 정적 자산과 연결된 서버리스 기능처럼 자주 수정되는 작업에는 자동 배포가 유용합니다. 개발자는 Git 커밋과 Pull Request 기록을 남기고, 운영자는 Cloudflare 대시보드에서 최근 빌드 상태와 배포 흐름을 확인할 수 있습니다. 즉, “누가 언제 무엇을 바꿨는지”와 “Cloudflare에 실제 반영됐는지”를 나눠서 추적할 수 있습니다.
2. 설정 전에 먼저 정할 네 가지
첫째, 연결할 저장소를 정합니다. Workers Builds는 GitHub 또는 GitLab 저장소 연결 흐름을 전제로 하므로, 운영용 Worker 코드가 어느 저장소에 있는지부터 분명해야 합니다. 개인 테스트 저장소와 운영 저장소가 섞여 있다면 운영용 저장소를 따로 분리하는 편이 안전합니다.
둘째, Cloudflare가 감시할 브랜치를 정합니다. 예를 들어 main 브랜치만 운영 배포로 쓰고, develop이나 feature 브랜치는 프리뷰 확인용으로만 쓰는 식입니다. 이 기준이 없으면 실험 커밋이 운영 Worker에 연결될 수 있습니다.
셋째, 빌드 명령이 필요한지 확인합니다. 순수 Worker 코드만 배포한다면 별도 빌드가 단순할 수 있지만, TypeScript, Astro, Next.js 일부 구성, 번들러가 들어간 프로젝트라면 npm run build 같은 단계가 필요할 수 있습니다. 공식 구성 문서도 커밋이 연결된 저장소에 들어오면 선택적 build command와 deploy command 흐름을 거친다고 설명합니다.
넷째, 배포 명령을 무엇으로 둘지 정합니다. Cloudflare 문서에서는 Worker 배포 명령 흐름을 구성할 수 있음을 안내합니다. 프로젝트가 Wrangler 기반인지, package.json 스크립트를 쓰는지, 환경별 변수를 어떻게 주입하는지에 따라 실제 명령은 달라질 수 있습니다.
3. 기본 설정 순서
- Cloudflare 대시보드에서 Workers & Pages 영역으로 이동해 대상 Worker 프로젝트를 확인합니다.
- Git 연동 또는 Builds 관련 설정에서 GitHub/GitLab 저장소 연결을 시작합니다.
- Cloudflare 앱이 접근할 저장소 범위를 최소한으로 선택합니다. 가능하면 모든 저장소 접근보다 필요한 저장소만 허용합니다.
- 운영 배포 기준 브랜치를 선택합니다. 일반적으로 main 또는 production 브랜치를 기준으로 둡니다.
- 빌드 명령이 필요한 프로젝트인지 확인합니다. 예: npm ci 뒤 npm run build가 필요한지, 별도 설치 없이 바로 배포 가능한지 점검합니다.
- 배포 명령을 확인합니다. Wrangler 배포 스크립트를 쓰는 경우 package.json scripts와 wrangler 설정 파일을 함께 맞춥니다.
- 첫 커밋 또는 수동 재실행으로 빌드 로그를 확인하고, 실패 시 의존성 설치·환경 변수·권한 문제를 순서대로 봅니다.
이 순서를 따르면 “저장소는 연결됐는데 배포가 안 된다”는 상황에서 원인을 좁히기 쉽습니다. 연결 권한 문제인지, 브랜치 선택 문제인지, 빌드 명령 실패인지, 배포 명령 실패인지가 단계별로 분리되기 때문입니다.
4. 브랜치와 프리뷰 빌드 설계
자동 배포에서 가장 중요한 것은 브랜치 정책입니다. 운영 Worker가 main 브랜치에 연결되어 있다면, main에 merge되는 순간 배포될 가능성이 있습니다. 따라서 Pull Request 리뷰, 테스트, 승인 흐름을 먼저 Git 쪽에 만들어 두는 것이 좋습니다. Cloudflare Builds 자체가 모든 팀의 코드 품질 기준을 대신해 주지는 않습니다. Builds는 “정해진 변경을 빌드하고 배포하는 통로”에 가깝습니다.
프리뷰 빌드는 기능 확인에 유용합니다. 다만 프리뷰 환경에서 실제 운영 API나 운영 데이터에 직접 접근하면 혼선이 생길 수 있습니다. 프리뷰 전용 변수, 테스트 엔드포인트, 제한된 샘플 데이터를 따로 두면 안전합니다. Cloudflare 화면과 옵션 이름은 업데이트로 바뀔 수 있으므로, 작업 전에는 공식 CI/CD와 Builds 문서를 한 번 더 확인하는 편이 좋습니다.
5. 빌드 명령과 배포 명령 체크리스트
| 확인 항목 | 질문 | 실무 메모 |
|---|---|---|
| 설치 단계 | npm ci 또는 pnpm install이 필요한가? | 패키지 매니저가 저장소와 빌드 환경에서 같아야 합니다. |
| 빌드 단계 | TypeScript 변환이나 번들링이 필요한가? | 필요 없다면 빌드 명령을 과하게 넣지 않는 편이 단순합니다. |
| 배포 단계 | wrangler deploy 또는 프로젝트 스크립트를 쓰는가? | 로컬에서 성공한 명령과 Cloudflare 설정 명령이 같은지 봅니다. |
| 환경 변수 | API URL, 토큰 이름, 환경 구분이 필요한가? | 민감 값은 코드에 넣지 말고 Cloudflare 설정에서 관리합니다. |
| 출력 로그 | 실패 시 어느 단계에서 멈추는가? | 설치 실패, 빌드 실패, 배포 실패를 나눠 기록합니다. |
6. 환경 변수와 권한을 다루는 방식
Workers 프로젝트는 외부 API, 데이터 저장소, 도메인 라우팅과 함께 쓰이는 경우가 많습니다. 그래서 자동 배포 설정에서는 환경 변수를 반드시 분리해 봐야 합니다. 개발용 변수, 프리뷰용 변수, 운영용 변수가 같은 이름으로 섞이면 테스트에서는 통과했지만 운영에서 다른 동작을 할 수 있습니다. Cloudflare 쪽에서 제공하는 변수·시크릿 관리 흐름과 Wrangler 설정 파일의 역할을 분리해 이해하는 것이 좋습니다.
저장소 접근 권한도 최소화가 기본입니다. GitHub 또는 GitLab 연결 시 조직 전체 저장소 접근이 필요한지, 특정 저장소만으로 충분한지 확인합니다. 또한 팀원이 퇴사하거나 외부 협업자가 빠졌을 때 저장소 권한과 Cloudflare 계정 권한을 함께 정리해야 합니다. 자동 배포는 편한 만큼 권한이 넓으면 영향 범위도 커집니다.
7. 첫 배포 후 확인할 로그
첫 자동 배포가 끝나면 성공 여부만 보지 말고 로그를 남겨야 합니다. 어떤 브랜치의 어떤 커밋이 실행됐는지, 빌드 명령은 무엇이었는지, 배포 명령은 정상 종료됐는지 확인합니다. 이후 문제가 생기면 이 첫 성공 로그가 기준점이 됩니다.
- 연결 저장소 이름과 브랜치가 의도한 값인지 확인
- 최근 커밋 SHA 또는 메시지가 빌드 로그와 맞는지 확인
- 빌드 명령이 실제로 실행됐는지, 생략됐는지 확인
- 배포 명령에서 권한 오류나 변수 누락이 없는지 확인
- Worker URL 또는 라우트에서 새 코드가 반영됐는지 간단한 요청으로 확인
8. 자주 막히는 지점
첫 번째는 브랜치 선택 오류입니다. 저장소는 맞게 연결했지만 Cloudflare가 다른 브랜치를 보고 있으면 push해도 배포가 시작되지 않습니다. 두 번째는 package-lock, pnpm-lock, yarn.lock 같은 잠금 파일과 실제 설치 명령이 맞지 않는 경우입니다. 로컬에서는 되는데 빌드 환경에서 실패한다면 패키지 매니저 차이를 먼저 확인합니다.
세 번째는 환경 변수 누락입니다. 로컬 .env에만 값이 있고 Cloudflare 설정에는 값이 없으면 배포 후 런타임에서 실패할 수 있습니다. 네 번째는 deploy command의 작업 디렉터리 문제입니다. 모노레포라면 Worker 코드가 하위 폴더에 있을 수 있으므로, 빌드·배포 명령이 어느 경로에서 실행되는지 확인해야 합니다.
9. 운영용으로 쓰기 전 최소 점검표
- 운영 브랜치와 프리뷰 브랜치를 구분했다.
- 저장소 접근 권한을 필요한 범위로만 허용했다.
- 빌드 명령과 배포 명령을 로컬에서 먼저 검증했다.
- 환경 변수와 시크릿을 코드가 아닌 설정으로 분리했다.
- 배포 실패 시 확인할 담당자와 로그 위치를 정했다.
- 도메인 라우팅이나 DNS 변경은 별도 체크리스트로 다룬다.
- Cloudflare 공식 화면, 기능, 플랜, 명령 예시는 업데이트로 바뀔 수 있음을 팀 문서에 남겼다.
10. 결론: 연결보다 설계가 먼저입니다
Cloudflare Workers Builds Git 자동 배포 설정은 버튼 몇 번으로 시작할 수 있지만, 운영 안정성은 연결 전에 정한 기준에서 갈립니다. 저장소, 브랜치, 빌드 명령, 배포 명령, 프리뷰와 운영 분리, 권한 범위를 먼저 정하면 자동 배포가 “불안한 자동화”가 아니라 “반복 가능한 배포 통로”가 됩니다. 처음에는 단일 Worker와 단일 브랜치로 작게 검증하고, 이후 팀 규칙과 프리뷰 환경을 늘리는 순서가 현실적입니다.
FAQ
Q1. Workers Builds는 GitHub만 가능한가요?
공식 문서에서는 Git 연동과 GitHub/GitLab 저장소 연결 흐름을 안내합니다. 실제 지원 범위와 화면은 계정 상태와 제품 업데이트에 따라 달라질 수 있으므로 연결 직전 Cloudflare 공식 문서를 확인해야 합니다.
Q2. 빌드 명령은 꼭 넣어야 하나요?
프로젝트에 따라 다릅니다. TypeScript 변환, 번들링, 프레임워크 빌드가 필요하면 빌드 명령을 둡니다. 단순 Worker라면 배포 명령만으로 충분할 수 있습니다.
Q3. push할 때마다 바로 운영에 반영되나요?
어떤 브랜치를 운영 배포로 연결했는지에 따라 달라집니다. main을 운영으로 연결했다면 main에 변경이 들어올 때 배포될 수 있으므로 Pull Request 리뷰와 브랜치 보호 규칙을 함께 쓰는 것이 좋습니다.
Q4. 실패하면 어디부터 봐야 하나요?
저장소 권한, 브랜치 선택, 설치 명령, 빌드 명령, 배포 명령, 환경 변수 순서로 나눠 봅니다. 로그에서 어느 단계가 실패했는지 먼저 분리하면 원인을 빨리 좁힐 수 있습니다.
Q5. 이 설정만 하면 도메인 연결도 자동으로 끝나나요?
아닙니다. Builds는 주로 코드 빌드와 배포 흐름을 다룹니다. 커스텀 도메인, 라우트, DNS 연결은 별도 설정이므로 운영 전에는 도메인 라우팅 체크리스트를 따로 확인해야 합니다.
