바로 답하면, Cloudflare Workers Deploy Hooks는 대시보드에서 브랜치별 호출 URL을 만들고 그 URL로 POST 요청을 보내 Workers Builds를 시작하는 방식으로 쓰면 됩니다. 수동으로 배포 버튼을 누르던 일을 CMS 저장, 정해진 시각의 Cron, Slack 봇, 내부 승인 도구와 연결하려는 팀이라면 먼저 훅 이름, 대상 브랜치, 호출 권한, 빌드 기록 확인 순서를 정해 두는 것이 핵심입니다.
요약: Deploy Hooks는 Workers Builds를 HTTP 요청으로 시작하는 연결점입니다. 운영자는 브랜치별 훅을 만들고, 외부 시스템에는 URL을 안전하게 보관한 뒤, build history의 Triggered by 표시와 배포 결과를 확인하면 됩니다. Cloudflare 화면, 요금, 권한, 기능명은 업데이트로 달라질 수 있으므로 실제 적용 전 공식 문서와 현재 대시보드를 다시 확인하세요.
1. 이 기능을 써야 하는 상황부터 확인하기
Workers 프로젝트가 Git 저장소와 연결되어 있고, 코드가 바뀔 때마다 자동 빌드되는 구조라면 기본 흐름만으로도 충분합니다. 하지만 콘텐츠 관리 화면에서 저장 버튼을 눌렀을 때, 사내 승인 버튼을 눌렀을 때, 정해진 시각에 정적 데이터를 다시 가져올 때처럼 코드 커밋이 없어도 빌드를 시작해야 하는 순간이 있습니다. 이때 Deploy Hooks가 중간 연결점이 됩니다.
실무에서는 “누가 대시보드에 들어가서 배포 버튼을 누를 것인가”보다 “어떤 시스템이 어떤 조건에서 빌드를 시작해야 하는가”를 먼저 정해야 합니다. 예를 들어 블로그 색인 파일을 갱신하는 봇, 상품 목록 JSON을 만드는 작은 작업, 고객 안내 페이지를 다시 빌드하는 CMS 저장 이벤트가 모두 후보가 될 수 있습니다. 다만 훅 URL은 호출만으로 빌드를 시작할 수 있으므로 공개 문서나 채팅방에 그대로 남기지 않는 편이 안전합니다.
2. 준비물: Workers Builds와 Git 연결 상태
Deploy Hooks는 Workers Builds 흐름 위에서 동작합니다. 따라서 먼저 Cloudflare Workers 프로젝트가 GitHub 또는 연결 가능한 Git 저장소와 묶여 있고, 기본 빌드 명령과 배포 브랜치가 정상인지 확인해야 합니다. 이 단계가 흔들리면 훅 호출 자체는 성공해 보여도 실제 빌드가 실패하거나 예상하지 않은 브랜치가 배포될 수 있습니다.
- Workers 프로젝트가 Cloudflare 대시보드에 존재하는지 확인합니다.
- Git 저장소, 기본 브랜치, 프리뷰 브랜치 규칙을 확인합니다.
- 빌드 명령, 출력 경로, 환경 변수 이름을 최신 값으로 맞춥니다.
- 수동 빌드 또는 일반 Git 푸시 빌드가 한 번 이상 성공했는지 확인합니다.
초기 설정이 끝나지 않은 프로젝트에 곧바로 훅을 붙이면 문제 원인을 찾기 어려워집니다. 먼저 대시보드에서 일반 빌드가 정상인지 확인하고, 그다음 훅을 만들어 외부 시스템과 연결하는 순서가 유지보수에 유리합니다.
3. Deploy Hook 생성 위치와 이름 정하기
공식 안내에 따르면 Workers Builds의 Deploy Hooks는 Cloudflare 대시보드에서 생성하고, 훅 이름과 대상 브랜치를 기준으로 빌드 기록에 표시됩니다. 이름은 나중에 build history에서 바로 이해할 수 있게 지어야 합니다. “hook-1”처럼 모호한 이름보다 “cms-prod-refresh”, “cron-preview-build”, “slack-approval-main”처럼 호출 주체와 목적을 함께 넣는 방식이 낫습니다.
브랜치 기준도 중요합니다. 운영 사이트에 곧장 반영되는 main 계열인지, 내부 검토용 preview 계열인지에 따라 훅을 분리해야 합니다. 같은 URL을 여러 자동화에 돌려 쓰면 추적이 어려워지므로, 호출 주체별로 훅을 나누고 이름 규칙을 문서화하는 편이 좋습니다.
4. 외부 시스템에서 POST로 호출하는 기본 흐름
Deploy Hook URL은 외부 시스템에서 HTTP 요청으로 호출합니다. CMS라면 게시물 저장 또는 발행 후 웹훅 설정에 URL을 넣고, Cron이라면 정해진 시간에 POST 요청을 보내도록 구성합니다. Slack 봇이나 내부 관리 도구라면 승인 버튼을 누른 뒤 서버 쪽에서 URL을 호출하게 만들 수 있습니다.
- Cloudflare에서 Deploy Hook을 만들고 URL을 복사합니다.
- 호출 주체의 비밀 값 저장 영역에 URL을 넣습니다.
- 테스트 이벤트 한 번으로 빌드가 시작되는지 확인합니다.
- Cloudflare build history에서 훅 이름과 결과를 확인합니다.
- 실패 알림을 받을 채널을 별도로 연결합니다.
중요한 점은 브라우저 주소창에 URL을 붙여 넣어 시험하는 습관을 피하는 것입니다. 실수로 기록에 남거나 공유될 수 있기 때문입니다. 가능하면 서버 환경 변수나 자동화 도구의 비밀 값 저장 기능을 사용하고, 테스트 호출도 로그가 남는 안전한 작업에서 수행하세요.
5. 브랜치별 운영 설계: main과 preview를 섞지 않기
운영 브랜치와 미리보기 브랜치를 같은 훅으로 처리하면 예상보다 빠르게 혼란이 생깁니다. 콘텐츠 팀은 미리보기만 원했는데 운영 반영 빌드가 시작될 수 있고, 개발팀은 실험 브랜치 확인만 원했는데 고객이 보는 주소가 바뀔 수 있습니다. 그래서 훅은 브랜치별로 나누고, 호출 도구 이름에도 브랜치를 드러내는 것이 좋습니다.
| 구분 | 추천 훅 이름 예시 | 주요 확인 |
|---|---|---|
| 운영 반영 | cms-main-refresh | 승인 조건, 호출 권한, 실패 알림 |
| 미리보기 | cms-preview-build | 검토 URL, 테스트 데이터, 자동 삭제 여부 |
| 정기 갱신 | cron-main-rebuild | 호출 주기, 중복 호출 제한, 결과 기록 |
| 내부 승인 | slack-approval-main | 승인자 범위, 버튼 로그, 재시도 절차 |
이 표는 그대로 팀 문서에 붙여도 됩니다. 실제 이름은 회사 규칙에 맞게 바꾸되, “누가”, “어느 브랜치”, “무슨 목적”인지 한눈에 보이도록 만드는 것이 핵심입니다.
6. 빌드 기록에서 확인해야 할 항목
Deploy Hook을 한 번 호출한 뒤에는 Cloudflare build history를 확인해야 합니다. 공식 설명처럼 훅으로 시작된 빌드는 Triggered by 열에서 훅 이름과 라벨로 식별할 수 있습니다. 이 기록을 기준으로 자동화가 정상 호출되었는지, 빌드가 어느 시점에 시작되었는지, 실패가 반복되는지 확인합니다.
운영 체크는 세 단계로 나누면 쉽습니다. 첫째, 요청이 실제로 빌드를 만들었는지 봅니다. 둘째, 빌드 명령이 끝까지 통과했는지 봅니다. 셋째, 배포된 결과가 의도한 브랜치와 맞는지 봅니다. 세 단계 중 하나라도 빠지면 자동화가 성공한 것처럼 보여도 사용자에게 보이는 결과는 다를 수 있습니다.
7. 실패를 줄이는 체크리스트
훅 자동화는 간단해 보이지만 운영에서는 작은 누락이 반복 빌드 실패로 이어집니다. 아래 체크리스트를 첫 적용 전에 한 번, 그리고 자동화 도구를 바꿀 때마다 다시 확인하세요.
- 훅 URL이 공개 저장소, 화면 캡처, 공개 문서에 들어가지 않았는지 확인했습니다.
- 운영 브랜치와 미리보기 브랜치 훅을 분리했습니다.
- 훅 이름만 봐도 호출 주체와 목적을 알 수 있습니다.
- 외부 도구의 재시도 설정이 과도한 반복 빌드를 만들지 않습니다.
- 빌드 실패 알림을 받을 채널을 정했습니다.
- 호출 성공과 배포 성공을 같은 의미로 보지 않도록 기록 기준을 나눴습니다.
- Cloudflare 대시보드 화면, 권한, 요금, 기능명이 바뀔 수 있음을 팀 문서에 남겼습니다.
8. CMS, Cron, Slack 봇 연결 예시
CMS 연결은 게시물 저장 후 사이트 빌드를 다시 시작하는 용도에 맞습니다. 다만 임시 저장마다 빌드가 돌면 사용량이 늘고 대기열이 길어질 수 있으므로, 발행 또는 승인 완료 이벤트에만 연결하는 편이 낫습니다. 콘텐츠가 자주 바뀌는 사이트라면 “초안 저장”과 “발행” 이벤트를 구분하세요.
Cron 연결은 매일 한 번 외부 데이터 파일을 다시 읽고 사이트를 새로 빌드하는 용도에 맞습니다. 예를 들어 가격표, 공지 목록, 정적 JSON을 최신화하는 작업이 여기에 해당합니다. Slack 봇 연결은 사람이 버튼으로 승인한 뒤 빌드를 시작하는 흐름에 적합합니다. 이때 봇이 훅 URL을 직접 보여주지 않고 서버에서만 호출하도록 만드는 것이 안전합니다.
9. 요금과 기능 변경 가능성 고지
Cloudflare의 대시보드 구성, Workers Builds 세부 화면, Deploy Hooks 생성 위치, 사용량 기준, 요금 또는 플랜별 제공 범위는 시간이 지나며 달라질 수 있습니다. 이 글은 공식 문서와 공개 검색 결과를 기준으로 한 설정 순서 안내이며, 실제 적용 전에는 현재 계정의 대시보드, 팀 권한, 프로젝트 설정, 최신 문서를 함께 확인해야 합니다.
특히 자동 빌드는 호출 횟수가 늘면 대기열, 빌드 시간, 로그 확인 방식에 영향을 줄 수 있습니다. 사내 도구나 고객용 페이지에 연결할 때는 테스트 프로젝트에서 먼저 호출 흐름을 확인하고, 운영 프로젝트에는 최소한의 훅만 남기는 방식이 안정적입니다.
10. 마무리: 작은 훅부터 만들고 기록을 남기기
Cloudflare Workers Deploy Hooks는 거창한 배포 시스템을 새로 만들지 않아도 외부 이벤트로 Workers Builds를 시작할 수 있게 해 줍니다. 첫 적용은 운영 브랜치가 아니라 미리보기 브랜치에서 시작하고, 훅 이름, 호출 주체, 실패 알림, 기록 확인 위치를 함께 남기는 것이 좋습니다. 이렇게 해 두면 CMS, Cron, Slack 봇, 내부 관리 도구를 차례로 붙여도 “어떤 호출이 어떤 빌드를 만들었는지” 추적할 수 있습니다.
FAQ
Q1. Deploy Hook URL만 알면 누구나 빌드를 시작할 수 있나요?
URL 자체가 호출 지점이므로 공개되면 원치 않는 빌드가 시작될 수 있습니다. 공개 저장소, 캡처 이미지, 공유 문서에 넣지 말고 자동화 도구의 비밀 값 저장 영역에 보관하세요.
Q2. Git 푸시 자동 빌드와 Deploy Hooks는 무엇이 다른가요?
Git 푸시 자동 빌드는 코드 변경을 기준으로 시작됩니다. Deploy Hooks는 CMS 저장, Cron, Slack 봇, 내부 버튼처럼 코드 변경이 없어도 외부 이벤트로 빌드를 시작할 때 쓰기 좋습니다.
Q3. 운영 브랜치와 미리보기 브랜치에 같은 훅을 써도 되나요?
권장하지 않습니다. 브랜치별 목적과 검수 흐름이 다르므로 훅을 분리하고 이름에 main, preview 같은 구분을 넣는 편이 안전합니다.
Q4. 호출은 성공했는데 배포 결과가 보이지 않으면 어디를 봐야 하나요?
먼저 Cloudflare build history에서 훅 이름으로 시작된 빌드가 있는지 확인합니다. 그다음 빌드 로그, 대상 브랜치, 출력 경로, 환경 변수 설정을 차례로 점검하세요.
Q5. 이 설정은 모든 계정에서 같은 화면으로 보이나요?
아닙니다. Cloudflare는 대시보드, 권한, 기능 제공 범위, 요금 기준을 계속 바꿀 수 있습니다. 실제 적용 시점에는 현재 계정 화면과 최신 공식 문서를 기준으로 확인해야 합니다.
