GitHub와 Cloudflare Workers를 연결하면 작업 브랜치에서 변경한 웹사이트를 Preview로 확인할 수 있다.
하지만 작업이 끝나 main에 병합하더라도 기존 Preview가 자동으로 삭제된다고 보장할 수는 없다. 마지막 배포 버전이 별도 주소로 남아 있을 수 있기 때문이다.
이 글에서는 GitHub Actions와 Cloudflare API를 연결해 운영 배포가 성공한 뒤 해당 Preview만 자동 정리하는 방법을 살펴본다.
1. 자동 정리의 기본 구조
자동화는 다음 순서로 동작하도록 구성한다.
- GitHub Pull Request가
main에 병합된다. - GitHub Actions가 실행된다.
- Cloudflare에서 병합 커밋의 Production Build 성공 여부를 확인한다.
- 해당 PR의 브랜치·커밋과 일치하는 Preview를 찾는다.
- 확인된 Workers Preview만 삭제한다.
Production 배포가 실패했거나 삭제 대상을 정확히 식별하지 못한다면 삭제하지 않도록 해야 한다. 자동화 이전에 만들어진 Preview는 별도로 조사해 정리해야 할 수도 있다.
2. Cloudflare API Token 생성
GitHub Actions에서 Cloudflare API를 호출하려면 인증용 API Token이 필요하다.
Cloudflare API Tokens 설정 페이지에 접속해 Create Token → Create Custom Token을 선택하고 용도를 알 수 있는 이름을 입력한다.
예시: Preview-Cleanup-Automation
필요한 권한
Workers Builds API에서 빌드 정보를 조회하고 Workers Preview를 삭제하는 구성이라면 다음 권한을 검토한다.
| Scope | Permission | Access |
|---|---|---|
| Account | Workers Builds Configuration | Edit |
| Account | Workers Scripts | Edit |
Workers Builds API는 사용자 범위(User-scoped)의 API Token을 요구한다. 권한 명칭과 필요한 범위는 Cloudflare 공식 문서 및 실제 사용하는 API에 맞춰 확인한다. 가능하면 필요한 권한만 부여한다.
그 밖의 토큰 설정
- Account Resources:
All accounts대신 자동화 대상 계정 하나로 범위를 제한한다. - Client IP Address Filtering: GitHub 호스팅 실행 환경의 IP 주소는 달라질 수 있다. 고정 IP를 사용하지 않는다면 비워둘 수 있다.
- TTL: 만료일 설정 여부는 운영 정책에 따라 선택한다. 만료일을 지정했다면 그전에 GitHub Secret도 갱신해야 한다.
Continue to summary → Create Token을 진행한 뒤 토큰 문자열을 안전하게 보관한다. 토큰 값은 생성한 뒤 다시 확인할 수 없을 수 있다.
Cloudflare의 배포용 Build Token과 GitHub Actions에서 API를 호출하는 API Token은 목적이 다르므로 구분해야 한다.
3. Cloudflare Account ID 확인
Cloudflare 대시보드에서 해당 계정의 Workers & Pages를 열고 Account Details의 Account ID를 확인한다. Cloudflare의 Account ID 확인 문서를 참고해도 좋다.
Account ID는 로그인 이메일 주소나 Zone ID가 아니다.
| 항목 | 의미 |
|---|---|
| Account ID | Cloudflare 계정 식별자 |
| Zone ID | 개별 도메인 영역의 식별자 |
| Cloudflare 로그인 이메일 주소 | |
| API Token | API 요청에 사용하는 비밀 인증 문자열 |
Account ID는 이메일 주소를 입력하는 칸이 아니다. 복사한 식별자가 실제 대상 계정의 것인지 확인해야 한다.
4. GitHub Actions Secrets 등록
GitHub에서 자동화 대상 저장소를 열고 다음 메뉴로 이동한다.
Settings → Secrets and variables → Actions → New repository secret
직접 접근하는 주소 형식은 아래와 같다.
https://github.com/OWNER/REPOSITORY/settings/secrets/actions
OWNER와 REPOSITORY는 자신의 계정 또는 조직과 저장소 이름으로 변경한다.
| Secret 이름 | 입력할 값 |
|---|---|
CLOUDFLARE_API_TOKEN | Cloudflare에서 생성한 API Token 문자열 |
CLOUDFLARE_ACCOUNT_ID | Cloudflare 계정의 Account ID |
왼쪽은 워크플로에서 참조하는 환경변수 이름이고, 오른쪽은 자신이 사용하는 실제 값이다. Secret 값은 Git 소스코드나 블로그 원고에 직접 넣지 않는다.
GitHub Secrets의 기존 값은 화면에서 다시 표시되지 않으므로 입력 오류가 있다면 올바른 값으로 업데이트한다.
5. GitHub Actions에 Preview 자동 정리 연결
워크플로는 저장소의 .github/workflows/ 디렉터리에 YAML 파일로 작성한다.
다음 조건을 확인하도록 구성한다.
pull_request의closed이벤트를 받는다.- PR이 실제로
main에 병합되었는지 확인한다. - 외부 Fork PR은 자동 정리 대상에서 제외한다.
- Cloudflare Production Build가 해당 병합 커밋 SHA로 성공했는지 확인한다.
- Cloudflare Builds API의 빌드 메타데이터에서 PR 브랜치·커밋·Preview URL을 대조한다.
- 일치하는 Workers Preview만 삭제한다.
Cloudflare가 제공하는 Wrangler의 Preview 삭제 기능을 이용할 수 있다. 다만 브랜치 문자열을 근거로 Preview 이름을 추측하거나, 개별 Deployment URL을 브랜치 Preview라고 가정해서는 안 된다.
Legacy Version Preview와 Workers Preview는 구분해서 다룬다. 삭제 여부를 판단할 증거가 부족하면 아무것도 삭제하지 않는 방식이 안전하다.
GitHub Actions를 사용하면 정해진 시각에 반복 실행하지 않고 PR 병합 이벤트를 기준으로 정리 절차를 시작할 수 있다.
6. 실제 발생했던 Account ID 오류
설정 과정에서 CLOUDFLARE_ACCOUNT_ID에 Cloudflare 계정의 이메일 주소를 잘못 입력한 적이 있다.
GitHub Actions는 시작되었지만 Worker 조회 단계에서 다음 오류가 발생했다.
Cloudflare Worker lookup failed with HTTP 404 (Cloudflare errors: 7003)
처음에는 API Token 권한 문제로 보일 수도 있는 상황이었다. 하지만 실제로 확인된 입력 오류는 Account ID 자리에 이메일 주소를 넣었다는 점이었다.
같은 오류가 발생한다면 다음 항목부터 확인한다.
- Account ID가 해당 Cloudflare 계정의 식별자인가?
- 이메일 주소나 Zone ID를 대신 입력하지 않았는가?
- API Token이 대상 계정에 적용되는가?
- 토큰에 Workers Builds 조회 및 Preview 삭제에 필요한 권한이 있는가?
GitHub Secrets의 값을 수정한 뒤 해당 GitHub Actions 워크플로를 다시 실행할 수 있다.
7. 자동 삭제가 완료되었는지 검증하기
GitHub 저장소의 Actions 탭에서 실행 기록을 확인한다.
GitHub Actions가 실행되었다는 사실만으로 Preview가 삭제됐다고 판단하지 않는다. 다음 항목을 확인해야 한다.
- 실제 Production 배포가 정상 완료되었는가?
- 이번 PR의 Preview만 삭제되었는가?
- 삭제 명령이 성공했는가?
- 이전 Preview URL에 더 이상 접근할 수 없는가?
대상을 식별하지 못했다면 삭제 작업을 건너뛰어야 한다. 운영 Worker와 다른 브랜치의 Preview는 영향을 받아서는 안 된다.
자동화는 반복 업무를 줄이지만, 인증·권한·대상 확인·실패 시 동작까지 검증해야 안전하게 사용할 수 있다.
이 글을 작성하게 된 배경
처음부터 Preview 자동 삭제 기능을 만들려고 했던 것은 아니다.
블로그 원고를 검수할 때마다 HTML 파일을 주고받는 불편함에서 출발해, GitHub 브랜치와 Cloudflare Preview를 활용하는 운영 방식을 고민하게 되었다.
그 과정에서 Preview가 병합 후에도 남을 수 있다는 사실을 알게 되었고, 이를 정리하기 위해 GitHub Actions를 활용했다.
처음의 불편함에서 자동화까지 생각이 확장된 과정은 Stories의 HTML 파일을 주고받다가, 블로그 운영 방식까지 바꾸고 싶어졌다에 기록했다.