링크 하나만 올리면 끝나는 일이었다
결론부터 말하면, Cloudflare Pages는 GitHub Actions 없이도 배포할 수 있다. Pages 프로젝트가 GitHub에 연동돼 있으면 푸시할 때마다 Cloudflare가 알아서 빌드하고 배포한다. Direct Upload 방식이라면 사이트 전체를 빌드해서 Wrangler로 올리면 된다. 이걸 깨닫기까지 꽤 돌아갔다.
하려던 일은 정말 작았다. 제휴 마케팅 서비스의 사이트 심사를 받으려고, 실제 글 하나에 외장 하드 상품 링크를 딱 하나 넣는 것이었다. 링크 위에는 "이 페이지에는 제휴 링크가 있으며, 구매 시 운영자가 수수료를 받을 수 있습니다"라는 안내 문구를 분명히 달았다. 링크를 만들고 글에 넣고 GitHub에 커밋했다.
여기까지는 끝났다.
그런데 GitHub에 코드가 올라간 순간, 착각 하나가 드러났다.
GitHub에 있는 것과 인터넷에 공개된 것은 다른 이야기다.
평소 쓰던 GitHub Actions는 쓸 수 없었다. 그러면 Cloudflare Worker로 그 페이지 하나만 가로채서 보여 주면 되지 않느냐는 의견도 나왔다. 하지만 이번 이용 조건에서는 그 방법도 쓸 수 없었다.
링크 하나 넣으려던 건데, 어느새 "CI는? Worker는? Pages는 Git 연동이야, Direct Upload야?" 하는 배포 회의가 시작됐다.
제휴 링크판 사그라다 파밀리아 2호관 착공이었다.
그런데 구조를 하나씩 떼어 놓고 보면 이야기가 갑자기 쉬워진다.
1. 왜 먼저 공개된 페이지가 있어야 했을까
Sovrn Commerce는 콘텐츠·블로그 운영자에게 이렇게 안내한다. 먼저 신청한 사이트에 Commerce 링크를 넣고 클릭이 생기게 한 다음, 그 후에 심사로 넘어간다.[3]
즉 "심사에 붙으면 링크를 단다"가 아니다. 심사하는 쪽이 실제로 달린 링크를 볼 수 있는 상태를 먼저 만들어야 한다.
Sovrn은 또 제휴 링크가 있는 페이지마다 수수료를 받는 관계라는 사실을 독자에게 알기 쉽게 알리라고 한다. 그 안내는 링크나 홍보보다 먼저 보이는 곳에 두라는 원칙도 있다.[4]
이번에 필요한 건 화려한 상품 비교 사이트가 아니다. 조건은 아주 소박하다.
- 신청한 사이트에 실제 글이 있다.
- 그 글 안에 제휴 링크가 있다.
- 링크보다 앞에 안내 문구가 있다.
- 공개 주소로 누구나 열어 볼 수 있다.
- 링크를 단 뒤 확인용 클릭을 몇 번 만들 수 있다.
여기서 중요한 건 끝에서 두 번째다. GitHub 저장소에 파일이 있다고 해서 공개된 웹페이지가 되는 건 아니다.
2. GitHub Actions가 멈춰도 Cloudflare Pages까지 멈추는 건 아니다
GitHub Actions는 GitHub 안에서 빌드, 테스트, 배포를 자동으로 돌려 주는 기능(CI/CD)이다.
반면 Cloudflare Pages에는 GitHub이나 GitLab을 바로 연결하는 자체 Git 연동 기능이 있다. 연결한 저장소에 푸시하면 Cloudflare가 직접 빌드하고 배포한다.[1]
흐름은 이렇다.
GitHub에 푸시 → Cloudflare Pages가 변경을 감지 → Cloudflare가 빌드 → Cloudflare가 배포
이 경로에는 GitHub Actions가 끼지 않는다.
이게 핵심이다. "GitHub Actions를 못 쓴다"가 곧 "GitHub에서 Cloudflare로 자동 배포를 못 한다"는 뜻은 아니다. 둘은 서로 다른 기능이다.
비유하자면 GitHub Actions는 우리 창고 안의 컨베이어 벨트이고, Cloudflare Git 연동은 택배 기사가 직접 와서 물건을 가져가는 계약이다.
컨베이어가 멈춰도 택배 차는 올 수 있다.
3. 먼저 지금 Pages 프로젝트가 어떤 방식인지 확인한다
Cloudflare Pages는 이걸 모르는 채로 손대면 순식간에 미로가 된다.
배포 방식은 크게 두 가지다.
| 방식 | 무엇으로 시작되나 | 빌드·배포는 누가 | 이럴 때 좋다 |
|---|---|---|---|
| Git 연동(Git integration) | GitHub/GitLab에 푸시 | Cloudflare | 저장소를 기준으로 자동 배포하고 싶을 때 |
| Direct Upload | 미리 빌드한 결과물 | Wrangler 또는 대시보드 | 내 컴퓨터나 다른 CI에서 빌드한 결과를 바로 올리고 싶을 때 |
Cloudflare 공식 문서에 따르면, Git 연동으로 만든 Pages 프로젝트는 나중에 일반 Direct Upload 프로젝트로 바꿀 수 없다. Git 연동 프로젝트에도 Wrangler로 수동 배포는 할 수 있지만, 대시보드에서 파일을 끌어다 놓는 방식은 쓸 수 없다.[1][2]
반대도 마찬가지다. Direct Upload로 시작한 프로젝트에 나중에 Git 연동을 붙일 수 없다. 자동 Git 배포로 옮기려면 새 Pages 프로젝트를 만들어야 한다.[2]
그래서 첫 질문은 "어떻게 배포하지?"가 아니다.
"지금 이 Pages 프로젝트는 Git 연동 방식인가, Direct Upload 방식인가?"
이것만 알면 선택지의 절반이 사라진다.
4. Git 연동 방식이라면 GitHub Actions를 되살릴 필요가 없다
GitHub 저장소와 Cloudflare Pages가 이미 제대로 연결돼 있다면, 가장 빠른 길은 Worker도 새 CI도 아니다.
Cloudflare Pages에서 다음을 확인한다.
- 올바른 GitHub 저장소가 연결돼 있는가
- 프로덕션 브랜치가 실제로 공개하고 싶은 브랜치인가
- 프로덕션 브랜치의 자동 빌드가 꺼져 있지 않은가
- 빌드 명령어와 출력 폴더가 지금 프로젝트와 맞는가
- 푸시한 뒤 Pages의 Deployments 화면에 새 배포가 생겼는가
pages.dev주소에서 새 글이 보이는가- 마지막으로 내 도메인에서도 같은 글이 보이는가
Cloudflare Git 연동은 연결된 브랜치의 커밋을 바탕으로 빌드와 배포를 한다.[1]
그러니 GitHub Actions를 잠깐 못 쓰더라도, Cloudflare 자체 빌드가 살아 있으면 공개는 계속할 수 있다.
여기서 할 일은 복잡한 시스템을 하나 더 짓는 게 아니라, 원래 있던 Cloudflare의 수거 창구가 열려 있는지 확인하는 것이다.
5. Direct Upload 방식이라면 한 페이지가 아니라 빌드 결과 전체를 올린다
Direct Upload는 완성된 정적 파일 묶음을 Cloudflare Pages에 넘기는 방식이다. 공식 문서는 미리 빌드한 파일을 Wrangler나 대시보드로 올리는 흐름을 안내한다.[2]
여기서 위험한 생각이 하나 떠오른다.
"이번에 바꾼 HTML 하나만 올리면 되지 않나?"
사이트 전체를 한꺼번에 빌드하는 구조라면 이건 웬만하면 피하는 게 좋다.
배포 단위는 "Git에서 바뀐 파일 하나"가 아니라 그 시점 사이트 전체의 빌드 결과물이기 때문이다. 글 목록, CSS, 자바스크립트, 검색 색인, 이미지, 주소 연결 규칙 같은 것들이 같이 만들어지는 구조라면, 한 장만 손으로 끼워 넣는 순간 실제 사이트와 저장소가 따로 놀게 된다.
Direct Upload를 쓴다면 기본 흐름은 이렇다.
최신 코드 받기 → 프로젝트 빌드 명령 실행 → 출력 폴더 확인 → 결과물 전체 배포 → 실제 주소 확인
예를 들어 Node 기반 정적 사이트라면 pnpm build 같은 프로젝트 전용 명령을 돌리고, 만들어진 dist 같은 폴더를 올린다.
중요한 건 실제 사이트를 "누가 파일 하나만 손으로 고친 정체불명의 다른 세상"으로 만들지 않는 것이다.
6. Worker라는 우회로를 못 쓴다면 깔끔하게 지운다
페이지 하나만 급하게 공개하고 싶을 때, 특정 주소만 Worker로 가로채는 아이디어 자체는 가능하다.
하지만 이번처럼 이용 조건상 Worker를 쓸 수 없다면, 그걸 중심으로 계획을 세워 봐야 의미가 없다.
"혹시 쓸 수 있을지도"라며 설계도에 남겨 둘수록 운영은 복잡해진다.
- GitHub Actions는 못 쓴다
- Worker도 못 쓴다
- 그러면 Cloudflare Pages의 Git 연동이나 Direct Upload 중 하나로 좁힌다
이거면 된다.
비상구를 열 개 만드는 것보다, 지금 열려 있는 정문 하나를 찾는 게 빠르다.
제휴 링크 하나 때문에 배포 시스템을 한 채 더 짓지 말자.
이게 이번에 얻은 가장 큰 교훈이었다.
7. 공개 완료는 커밋이 아니라 실제 페이지로 판단한다
웹사이트를 운영하면서 위험한 건, 중간 단계를 "완료"라고 부르는 것이다.
- 코드를 썼다
- GitHub에 커밋했다
- 빌드가 통과했다
- Cloudflare에 배포가 생겼다
모두 중요하지만, 독자가 보는 건 최종 주소뿐이다.
이번 같은 제휴 심사용 페이지라면 마지막에 이걸 확인한다.
- 공개 주소가 시크릿 창에서도 열린다.
- 최신 글 내용이 보인다.
- 제휴 안내 문구가 링크보다 앞에 보인다.
- 상품 링크가 원하는 곳으로 이동한다.
- 휴대폰에서도 화면이 깨지지 않는다.
- 필요하면 확인용 클릭을 몇 번 만든다.
- Sovrn 관리 화면에서 클릭 집계와 심사 상태를 확인한다.
Sovrn은 콘텐츠·블로그 캠페인을 링크를 달고 클릭이 생긴 뒤에 심사하는 흐름으로 설명한다.[3]
그러니 "GitHub에 올렸으니 심사 대기"가 아니라, 실제 주소에서 링크를 보여 줄 수 있는 상태가 되어야 비로소 출발선이다.
8. 그다음엔 제휴 링크를 글 본문에 박아 넣지 않는 게 낫다
이번 링크 하나는 손으로 넣어도 괜찮다.
하지만 글이 수백, 수천 개로 늘어나면 매번 "이 글에 광고를 넣나? 어디에? 어떤 상품? 어느 나라?"를 사람이 정하게 되고, 글 공장 옆에 광고 공장이 하나 더 생긴다.
다음 단계에서는 글 본문과 수익화 정보를 따로 두는 게 관리하기 편하다.
예를 들어 글에는 이런 작은 설정만 붙여 둔다.
article_id: example-123
affiliate: true
placement: after_solution
max_products: 3
market_mode: auto
product_theme: external-storage
그리고 공개할 때 이렇게 흘려보낸다.
글 → 수익화 여부 확인 → 상품 후보 → 제휴 링크 생성 → 화면을 그릴 때 끼워 넣기 → 성과 측정
본문은 오래 남는 자산으로 두고, 상품 주소·재고·판매처·나라별 연결은 바꿔 끼울 수 있는 부품으로 만든다.
이러면 링크가 끊기거나 상품이 바뀔 때마다 12개 언어 본문을 다 뒤질 필요가 없다.
제휴 링크는 글 그 자체가 아니다.
나중에 글에 연결하는 영업용 배관 정도로 다루는 게 오래 운영하기에 훨씬 튼튼하다.
9. 결론: CI가 막히면 새 성을 짓기 전에 Cloudflare 입구부터 확인하자
이번 일은 꽤 상징적이었다.
시작은 "심사용으로 외장 하드 링크 하나 달자"였다.
링크는 만들었다. 안내 문구도 썼다. GitHub에도 올렸다.
그런데 실제로 공개하려니 GitHub Actions를 못 썼다. Worker로 돌아가려 해도 그 길도 막혀 있었다.
여기서 새 시스템을 또 붙이면, 목표가 "링크 공개"에서 "배포 시스템 증축"으로 바뀌어 버린다.
정리하면 판단은 이것뿐이다.
- 지금 Pages가 Git 연동 방식이면 Cloudflare 자체 빌드를 쓴다.
- Direct Upload 방식이면 사이트 전체를 빌드해서 정식 결과물을 배포한다.
- Worker를 못 쓰면 후보에서 지운다.
- GitHub 커밋을 공개 완료라고 부르지 않는다.
- 실제 공개 주소에서 안내 문구, 링크, 화면, 클릭을 확인한다.
기술적으로 가장 위험한 건 선택지가 적은 게 아니다.
쓸 수 없는 선택지가 설계도에 계속 남아 있는 것이다.
