API de redirecionamento e regras como código: CI/CD para mudanças de URL com menos risco

Um redirect quase sempre começa pequeno. Uma URL de produto muda. Um post antigo sai do ar. Uma landing de campanha ganha outro slug. Alguém coloca uma regra no next.config.js, no Cloudflare, num plugin de CMS ou no Nginx.

Isso funciona até o redirect virar operação de lançamento.

Em ecommerce, migração de domínio, catálogo VTEX, Shopify, Nuvemshop, WordPress, campanhas com WhatsApp, Instagram, QR code e afiliados, uma regra define para onde vão backlinks, anúncios, emails, cupons e links antigos. Não é detalhe técnico. É configuração de tráfego em produção.

O caminho mais seguro é tratar redirects como configuração publicável: regras estruturadas, CI validando, staging mostrando comportamento real, snapshot versionado em produção e rollback pronto.

Por que redirects precisam entrar no release

Times já revisam variáveis de ambiente, feature flags, migrations e middleware. Uma regra que afeta SEO, mídia paga ou receita merece o mesmo processo.

O fluxo fraco costuma ser assim:

• SEO mantém uma planilha
• engenharia copia linhas para a configuração da aplicação
• marketing muda destinos de campanha em outra ferramenta
• o CMS cria redirects escondidos
• o CDN normaliza domínio
• quando o relatório quebra, ninguém sabe qual camada respondeu

Regras como código criam um artefato comum de revisão. Pode ser YAML, JSON, Terraform, CSV ou payload de API interna. O ponto é que a regra tenha dono, teste e volta.

Uma regra precisa explicar intenção

old_url e new_url bastam para redirecionar. Não bastam para operar com segurança.

Use um contrato que descreva o motivo:

{
  "source": "/precos-antigos",
  "destination": "/precos",
  "status": 301,
  "match": "exact",
  "queryPolicy": "preserve_allowlist",
  "preserveQuery": ["utm_source", "utm_medium", "utm_campaign", "gclid"],
  "owner": "growth",
  "reason": "consolidacao da pagina de precos",
  "expiresAt": null
}

Em migrações e lojas, inclua prioridade, locale, país, dispositivo, lote, revisão e fallback.

Google orienta a escolher redirect pela intenção e duração da mudança. CI não substitui essa decisão, mas bloqueia uma regra temporária sendo publicada como 301 permanente.

API sync evita copia e cola

Redirects nascem fora do repositório. O CMS muda slug. Um produto sai do catálogo. Uma agência entrega mapa de migração. Um parceiro precisa de link com marca. Um time de docs muda a versão publicada.

Se tudo vira importação manual, a operação perde controle.

Uma API de redirecionamento cria um limite claro:

Cloudflare expõe redirects pela Rulesets API. Next.js e Vercel também suportam redirects por configuração. Essas camadas executam. O desafio real é governança: validação, dono, staging, analytics e rollback.

O que o CI deve validar

Um job de CI para redirects precisa testar comportamento, não só sintaxe.

Checks importantes:

• fontes duplicadas
• destinos malformados
• regra sem owner, motivo ou status
• wildcard ou regex escondendo regra exata
• status permanente em campanha com fim previsto
• destino com 404, 410, 5xx ou redirect inesperado
• chains longas
• loops
• perda de UTM, click ID, cupom ou partner ID
• condição de país, dispositivo, header ou query sem fallback
• conflito com outro lote

Para URLs críticas, rode uma matriz:

source=/precos-antigos
country=BR
device=desktop
query=?utm_source=google&gclid=test
expectedStatus=301
expectedDestination=/precos?utm_source=google&gclid=test

Isso tira o redirect do improviso e coloca dentro do release.

Staging deve mostrar o destino final

Um staging de redirects precisa responder: com esta URL e este contexto, o que acontece em produção?

Mostre:

• regra aplicada
• status code
• destino final
• política de query
• resultado das condições
• regras concorrentes
• tamanho da chain
• owner e lote
• diff contra o snapshot publicado

GitHub Actions permite ambientes com reviewers antes do deploy. O mesmo padrão funciona para redirects: CI valida, staging mostra evidência e produção espera aprovação.

Rollback não pode depender de redeploy

Reverter redirect não deveria exigir deploy da aplicação de origem durante um pico de campanha.

Mantenha snapshots publicados. Marque importações por lote. Separe regras temporárias de campanhas das migrações permanentes. Deixe overrides emergenciais visíveis.

Se a regra afeta busca, tráfego pago, suporte ou vendas, rollback faz parte do requisito.

Onde o UrlEdge entra

UrlEdge ajuda quando o time quer automatizar redirects sem fazer deploy da aplicação para cada mudança de URL.

• API para domínios, regras, publicação e automação
• Redirect Management para ownership, analytics, snapshots e rollback
• Bulk URL Management para mapas de migração e imports grandes
• Advanced Redirect Rules para wildcard, regex, query e condições
• Redirect Checker para QA de rota e status
• Collaboration para revisão entre SEO, marketing, plataforma e agência

Deixe na aplicação os redirects pequenos que pertencem ao produto. Deixe no CDN a normalização simples. Use API e regras como código quando você precisa de revisão, evidência, automação e recuperação rápida.

FAQ

O que são redirects como código?

São regras em formato estruturado e revisável, passando por validação, staging, publicação e rollback como qualquer configuração de produção.

Todo redirect deve ficar no Git?

Não. Git é bom para regras estáveis e migrações. API sync é melhor quando as regras vêm de CMS, ecommerce, parceiros ou ferramentas internas.

CI/CD pode publicar redirects direto?

Pode, desde que exista validação, staging, permissões, aprovação para mudanças de risco e rollback.

Referências

• 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