링크 하나만 올리면 되는 일이었다
처음 목적은 아주 작았다. 제휴 플랫폼의 사이트 심사를 진행하기 위해 외장 HDD 상품 링크 하나를 실제 기사에 넣는 일이었다.
기사에는 제휴 링크보다 앞에 보상 관계를 알리는 고지문이 있어야 하고, 링크는 실제 상품 페이지로 작동해야 한다. 링크를 만들고 글에 넣고 GitHub에 커밋하는 것까지는 끝났다.
문제는 그다음이었다.
GitHub에 코드가 있다는 것과 인터넷에 페이지가 공개됐다는 것은 전혀 다른 상태다.
평소 사용하던 GitHub Actions 경로는 사용할 수 없었다. 특정 URL만 Cloudflare Worker로 가로채 임시 공개하는 방법도 검토했지만, 현재 운영 조건에서는 Worker 경로도 사용할 수 없었다.
링크 하나를 올리려다가 CI, Worker, Pages, Git integration, Direct Upload를 전부 검토하는 회의가 시작됐다.
제휴용 사그라다 파밀리아 2호관을 착공할 분위기였다.
하지만 배포 방식을 분리해 보면 문제는 훨씬 단순해진다.
1. 왜 먼저 실제 공개 페이지가 필요했을까
Sovrn Commerce의 콘텐츠·블로그 온보딩 가이드는 캠페인 심사 전에 Commerce 링크를 사이트에 구현하고 클릭을 발생시키는 흐름을 안내한다.[3]
즉 “승인 후 링크 설치”만 있는 구조가 아니다. 심사자가 실제 구현 예시를 볼 수 있어야 한다.
또한 Sovrn은 제휴 링크가 있는 페이지에서 독자가 보상 관계를 이해할 수 있도록 명확한 disclosure를 제공하고, 링크나 프로모션보다 먼저 보이게 하는 원칙을 안내한다.[4]
기본적인 심사 페이지에 필요한 것은 거창하지 않다.
- 제출한 사이트에 실제 기사가 있다.
- 기사 안에 제휴 링크가 있다.
- 링크보다 앞에 disclosure가 있다.
- 공개 URL로 누구나 페이지를 열 수 있다.
- 구현 후 소수의 확인 클릭을 만들 수 있다.
여기서 핵심은 repository 안의 파일과 공개 웹페이지를 같은 것으로 취급하지 않는 것이다.
2. GitHub Actions를 못 쓴다고 Cloudflare Pages까지 멈추는 것은 아니다
GitHub Actions는 GitHub에서 build, test, deploy를 실행하는 CI/CD 기능이다.
Cloudflare Pages에는 별도의 Git integration이 있다. GitHub 또는 GitLab repository를 Pages에 직접 연결하면, 연결된 repository에 push가 들어올 때 Cloudflare가 자체적으로 build와 deploy를 실행할 수 있다.[1]
흐름은 다음과 같다.
GitHub push → Cloudflare Pages가 commit 감지 → Cloudflare build → Cloudflare deploy
이 경로에는 GitHub Actions workflow가 필수 요소가 아니다.
따라서 “Actions를 사용할 수 없다”와 “GitHub에서 Cloudflare로 자동 배포할 수 없다”는 같은 문장이 아니다.
GitHub Actions가 내부 컨베이어라면 Cloudflare Git integration은 창고로 직접 와서 물건을 가져가는 택배 계약에 가깝다.
컨베이어가 멈춰도 수거 차량은 움직일 수 있다.
3. 먼저 기존 Pages 프로젝트의 유형을 확인한다
Cloudflare Pages에는 크게 두 배포 방식이 있다.
| 방식 | 시작점 | build/deploy 위치 | 적합한 경우 |
|---|---|---|---|
| Git integration | GitHub/GitLab push | Cloudflare | repository를 기준으로 자동 배포하고 싶을 때 |
| Direct Upload | 미리 만든 build 결과물 | Wrangler 또는 dashboard | 로컬이나 별도 CI에서 build 후 직접 올릴 때 |
Cloudflare 문서에 따르면 Git integration으로 만든 프로젝트를 나중에 일반 Direct Upload 프로젝트로 그대로 전환할 수는 없다. Git 연결 프로젝트도 Wrangler를 이용한 수동 배포는 가능하지만 기존 Git 연결 프로젝트에 dashboard drag-and-drop을 쓰는 방식은 지원되지 않는다.[1][2]
반대로 Direct Upload로 시작한 프로젝트에 나중에 같은 프로젝트 그대로 Git integration을 붙일 수도 없다. 자동 Git 배포로 바꾸려면 새 Pages 프로젝트가 필요하다.[2]
그래서 첫 질문은 “어떤 우회 방법을 쓰지?”가 아니다.
“지금 이 Pages 프로젝트는 Git integration형인가, Direct Upload형인가?”
이것만 확인해도 선택지가 크게 줄어든다.
4. Git integration형이라면 GitHub Actions를 되살릴 필요가 없다
이미 GitHub repository와 Cloudflare Pages가 올바르게 연결돼 있다면 가장 짧은 길은 Worker도 새 CI도 아니다.
Pages 설정에서 다음을 확인한다.
- 올바른 GitHub repository가 연결돼 있는가
- production branch가 실제 배포 branch인가
- 해당 branch의 자동 build가 비활성화돼 있지 않은가
- build command와 output directory가 현재 프로젝트와 맞는가
- push 후 Pages의 Deployments 화면에 새 deployment가 생성되는가
pages.devURL에서 새 내용이 보이는가- custom domain에서도 동일한 내용이 보이는가
Cloudflare Git integration은 연결된 repository의 commit을 바탕으로 build와 deploy를 수행한다.[1]
이 경로가 살아 있다면 GitHub Actions의 일시적 제한 때문에 별도 배포 시스템을 새로 만들 이유가 없다.
새 비상통로를 파기 전에 정문이 열려 있는지 확인하면 된다.
5. Direct Upload형이라면 한 페이지가 아니라 build 결과물을 배포한다
Direct Upload는 미리 build한 asset을 Pages에 올리는 방식이다. Cloudflare는 Direct Upload 프로젝트에서 Wrangler 또는 dashboard drag-and-drop을 지원한다.[2]
여기서 “이번에 바꾼 HTML 하나만 올리면 되지 않을까?”라는 생각이 들기 쉽다.
정적 사이트 생성기 기반 사이트라면 보통 좋지 않은 방법이다.
배포 단위는 수정한 source file 하나가 아니라 사이트 전체 build output이다. build 과정에서 routing, CSS, JavaScript, 검색 index, metadata, 다른 페이지까지 함께 생성될 수 있기 때문이다.
안전한 흐름은 다음과 같다.
최신 source 확보 → project build 실행 → output directory 확인 → 전체 결과물 deploy → 실제 URL 확인
Node 기반 정적 사이트라면 pnpm build 같은 프로젝트별 명령으로 dist 같은 output directory를 만들 수 있다.
본번을 repository와 다른 수동 편집 세계로 만들지 않는 것이 중요하다.
6. Worker를 쓸 수 없다면 설계에서 지운다
긴급한 한 URL만 Worker route로 처리하는 아이디어 자체는 기술적으로 가능하다.
하지만 현재 환경에서 Worker를 사용할 수 없다면 그 방식을 주력 대안으로 남겨 둘 이유가 없다.
- GitHub Actions 사용 불가
- Worker 경로 사용 불가
- 그러면 기존 Pages Git integration 또는 유효한 Direct Upload 경로 중 하나만 선택
이렇게 줄이면 된다.
비상구를 열 개 만드는 것보다 지금 실제로 열리는 문 하나를 확인하는 편이 빠르다.
제휴 링크 하나 때문에 두 번째 배포 플랫폼을 만들 필요는 없다.
7. 공개 완료는 commit SHA가 아니라 실제 페이지로 증명한다
코드 작성, commit, build 성공, deployment 생성은 모두 중간 단계다.
최종 확인은 실제 독자가 보는 URL에서 해야 한다.
제휴 심사 페이지라면 다음을 본다.
- 공개 URL이 새 브라우저 세션에서도 열린다.
- 최신 본문이 보인다.
- disclosure가 제휴 링크보다 앞에 있다.
- 상품 링크가 의도한 목적지로 이동한다.
- 모바일에서도 깨지지 않는다.
- 필요하면 소수의 확인 클릭을 발생시킨다.
- Sovrn에서 클릭이나 심사 상태를 확인한다.
Sovrn은 콘텐츠·블로그 캠페인에 대해 링크 구현과 클릭 생성 후 심사하는 절차를 설명한다.[3]
따라서 “GitHub에 넣었다”가 아니라 심사자가 실제 사이트에서 구현을 볼 수 있는 상태가 시작점이다.
8. 규모가 커지면 제휴 URL을 본문에 직접 박지 않는 편이 낫다
링크 하나는 수동으로 처리해도 된다.
하지만 기사 수가 수백, 수천으로 늘어나면 매번 광고 여부, 위치, 상품, 국가를 수동 결정하는 순간 기사 공장 옆에 광고 공장이 생긴다.
장기적으로는 editorial content와 commercial metadata를 분리하는 편이 낫다.
article_id: example-123
affiliate: true
placement: after_solution
max_products: 3
market_mode: auto
product_theme: external-storage
이후 흐름은 다음처럼 만들 수 있다.
article → monetization gate → product candidate → affiliate link creation → renderer insertion → performance measurement
본문은 장기 자산으로 남기고 상품 URL, 재고, merchant, 국가별 routing은 교체 가능한 부품으로 둔다.
제휴 시스템은 기사 자체가 아니라 기사에 연결되는 영업 배관처럼 다루는 편이 강하다.
9. 결론: CI가 막혔을 때 새 성을 짓기 전에 Cloudflare의 실제 입구부터 확인하자
시작은 HDD 제휴 링크 하나였다.
링크도 만들었고 disclosure도 작성했고 source도 GitHub에 들어갔다.
하지만 CI 경로가 막혔고 Worker 우회도 사용할 수 없었다.
여기서 또 다른 시스템을 추가하면 목표가 “링크 공개”에서 “새 배포 플랫폼 건설”로 바뀐다.
판단은 훨씬 간단하다.
- 기존 Pages가 Git integration형이면 Cloudflare native Git build를 사용한다.
- Direct Upload형이면 전체 사이트를 build하고 지원되는 방식으로 결과물을 deploy한다.
- Worker가 사용할 수 없다면 후보에서 삭제한다.
- Git commit을 production 완료라고 부르지 않는다.
- 실제 공개 URL에서 disclosure, 링크, 표시, 클릭을 확인한다.
가장 위험한 구조는 선택지가 적은 구조가 아니다.
사용할 수 없는 선택지가 설계도에 영원히 남아 있는 구조다.
