리디렉션 API와 Rules as Code: URL 변경을 CI/CD로 안전하게 운영하기

리디렉션은 보통 작은 수정으로 시작합니다. 상품 URL이 바뀝니다. 고객센터 문서가 이동합니다. 캠페인 랜딩 페이지 slug가 바뀝니다. 누군가 next.config.js, Cloudflare, CMS 플러그인, Nginx에 규칙을 추가합니다.

몇 개라면 괜찮습니다. 쇼핑몰 리뉴얼, 도메인 이전, Cafe24나 Shopify에서 headless로 가는 작업, Kakao와 광고 캠페인, 파트너 링크가 섞이면 이야기가 달라집니다.

리디렉션 규칙은 오래된 검색 유입, QR 코드, 광고 클릭, 이메일, 제휴 링크, 문서 URL이 어디로 가는지 결정합니다. 이것은 단순 설정이 아니라 운영 트래픽 설정입니다.

더 안전한 모델은 리디렉션을 배포 가능한 설정으로 취급하는 것입니다. 규칙을 구조화하고, CI에서 검증하고, 스테이징에서 실제 동작을 확인하고, 운영에는 버전 스냅샷을 배포하며, 롤백을 미리 준비합니다.

리디렉션을 릴리스 흐름에 넣어야 하는 이유

개발팀은 이미 환경 변수, DB migration, feature flag, middleware를 리뷰합니다. SEO, 광고, 매출에 영향을 주는 리디렉션도 같은 수준의 절차가 필요합니다.

약한 운영 방식은 자주 이렇게 됩니다.

• SEO 팀은 스프레드시트를 관리합니다
• 개발팀은 일부 규칙을 앱 설정에 복사합니다
• 마케팅은 캠페인 목적지를 다른 도구에서 바꿉니다
• CMS 플러그인이 별도 리디렉션을 만듭니다
• CDN은 호스트 정규화를 합니다
• 문제가 생기면 어느 계층이 응답했는지 모릅니다

Rules as Code는 redirect map을 리뷰 가능한 산출물로 만듭니다. YAML, JSON, Terraform, CSV, API payload 모두 가능합니다. 중요한 것은 소유자, 테스트, 롤백입니다.

source와 destination만으로는 부족합니다

old_url과 new_url만 있어도 리디렉션은 됩니다. 하지만 안전하게 운영하기에는 정보가 부족합니다.

의도를 담은 계약이 필요합니다.

{
  "source": "/old-pricing",
  "destination": "/pricing",
  "status": 301,
  "match": "exact",
  "queryPolicy": "preserve_allowlist",
  "preserveQuery": ["utm_source", "utm_medium", "utm_campaign", "gclid"],
  "owner": "growth",
  "reason": "pricing page consolidation",
  "expiresAt": null
}

이커머스나 마이그레이션에서는 priority, locale, country, device, batch, review status, fallback도 필요합니다.

Google의 리디렉션 가이드도 영구/임시 의도와 검색 결과에 남길 URL을 기준으로 설명합니다. CI가 판단을 대신할 수는 없지만, 위험한 조합은 막을 수 있습니다.

API sync는 수동 복사를 줄입니다

리디렉션은 저장소 밖에서 생깁니다. CMS slug가 바뀝니다. 상품이 단종됩니다. 문서 버전이 바뀝니다. SEO 대행사가 마이그레이션 맵을 줍니다. 파트너용 브랜드 링크가 필요해집니다.

이 모든 것을 수동으로 옮기면 규칙이 금방 어긋납니다.

Redirect API는 경계를 명확하게 만듭니다.

Cloudflare는 Rulesets API로 redirect rule을 만들 수 있습니다. Next.js와 Vercel도 config 기반 redirects를 지원합니다. 실행 계층은 존재합니다. 어려운 부분은 validation, owner, staging, analytics, rollback입니다.

CI가 확인해야 할 것

리디렉션 CI는 문법만이 아니라 동작을 테스트해야 합니다.

확인할 항목:

• 중복 source
• 잘못된 destination
• owner, reason, status 누락
• exact rule을 가리는 wildcard나 regex
• 기간이 있는 캠페인에 permanent status 사용
• destination의 404, 410, 5xx 또는 예상 밖 redirect
• 긴 redirect chain
• loop
• UTM, click ID, coupon, partner ID 손실
• country, device, header, query 조건의 fallback 여부
• 다른 batch와의 충돌

중요 URL은 request matrix로 테스트합니다.

source=/old-pricing
country=KR
device=desktop
query=?utm_source=google&gclid=test
expectedStatus=301
expectedDestination=/pricing?utm_source=google&gclid=test

이렇게 해야 배포 전 목적지를 설명할 수 있습니다.

스테이징은 최종 경로를 보여줘야 합니다

리디렉션 스테이징은 질문 하나에 답해야 합니다. 이 URL과 이 요청 조건이면 운영에서 무슨 일이 일어나는가?

보여줄 정보:

• 매칭된 규칙
• status code
• final destination
• query handling
• condition result
• competing rules
• chain length
• owner와 batch
• published snapshot과의 diff

GitHub Actions environments는 deployment 전에 reviewer를 요구할 수 있습니다. 같은 패턴을 리디렉션에도 적용할 수 있습니다. CI가 검증하고, staging이 증거를 보여주고, production publish는 올바른 owner의 승인을 기다립니다.

롤백은 요구사항입니다

리디렉션 롤백 때문에 origin app을 다시 배포하면 안 됩니다.

배포된 snapshot을 보관합니다. import batch에 tag를 붙입니다. 임시 캠페인 규칙과 영구 migration 규칙을 분리합니다. emergency override는 보이는 곳에 둡니다.

검색, 광고, support, 매출에 영향을 줄 수 있다면 rollback은 기능의 일부입니다.

UrlEdge가 맞는 지점

UrlEdge는 URL 변경마다 origin deploy를 하고 싶지 않은 팀을 위한 redirect workflow입니다.

• API로 domains, rules, publishing, automation 처리
• Redirect Management로 ownership, analytics, snapshots, rollback 관리
• Bulk URL Management로 migration map과 대량 import 처리
• Advanced Redirect Rules로 wildcard, regex, query, condition 처리
• Redirect Checker로 route와 status QA
• Collaboration으로 SEO, marketing, platform, agency 리뷰 정렬

작은 앱 소유 redirect는 app config에 남겨도 됩니다. 단순 host normalization은 CDN이 맡아도 됩니다. review, evidence, automation, fast recovery가 필요해지면 Redirect API와 Rules as Code가 더 적합합니다.

FAQ

Redirect rules as code란 무엇인가요?

리디렉션 규칙을 구조화되고 리뷰 가능한 형식으로 관리하고, validation, staging, publish, rollback을 거치게 하는 운영 방식입니다.

모든 redirect를 Git에 둬야 하나요?

아닙니다. 안정적인 migration rule은 Git에 적합합니다. CMS, ecommerce, partner, internal tool에서 생기는 rule은 API sync가 더 적합합니다.

CI/CD에서 바로 publish해도 되나요?

가능합니다. 다만 validation, staging evidence, 권한, 위험 변경 승인, rollback이 있어야 합니다.

참고 자료

• Google Search Central: Redirects and Google Search
• Cloudflare Rules docs: Create a redirect rule via API
• Next.js docs: next.config.js redirects
• GitHub Docs: Managing environments for deployment