Dois triggers, um id de KV: por que os builds de preview estavam apagados no imperfectsystems.com

Os builds de branches que não são de produção neste site estavam apagados desde o início de julho. Você dá push numa feature branch, não recebe nada de volta do Cloudflare, nenhuma preview URL, nenhum check no PR, nada. A base de conhecimento do repositório tinha uma nota sobre isso: npx wrangler versions upload estava auto-provisionando um namespace do KV pra algo chamado SESSION e colidindo com o de produção. Corrigir isso precisava de “um id/preview_id de verdade” fixado no wrangler.toml. Esse era o plano no início. Não era a história inteira.

De onde vem um binding SESSION, afinal?

Primeira surpresa: nada nesta base de código usa sessões do Astro. Nenhum Astro.session em lugar nenhum. Então por que um build precisava de um namespace do KV chamado SESSION?

Acontece que o @astrojs/cloudflare ativa sessões apoiadas em KV por padrão, use você ou não, a menos que você configure explicitamente um driver diferente. Ele registra isso bem na saída do build, se você estiver de olho:

[@astrojs/cloudflare] Enabling sessions with Cloudflare KV with the "SESSION" KV binding.

Isso injeta uma entrada kv_namespaces sem id na config gerada do build. Sem id significa que o Cloudflare tenta auto-provisionar um a cada deploy. Já que o site nunca toca em sessões, o fix foi simples assim que encontrei: criar um namespace de verdade e fixar seu id no wrangler.toml, igual o binding GAME_FILES já existente faz. Nada nunca lê ou escreve nele, ele só precisa existir pra que o adapter pare de improvisar.

Eu tinha assumido que também precisaria de um preview_id pra um segundo namespace, só de preview, foi o que a nota original dizia. Checar a documentação do Cloudflare e rodar wrangler versions upload --dry-run localmente mostrou que isso não existe aqui: preview_id é um conceito do wrangler dev --remote, e o caminho de preview do Workers Builds nunca lê ele. Um único id fixado cobre produção e preview.

O fix do KV não era o bug inteiro

Refiz o build localmente, confirmei que a config gerada agora mostrava um id de verdade, e estava pronto pra dar como resolvido. Antes de mesclar, perguntei direto ao Cloudflare como de fato era o trigger de build deste repositório, e encontrei exatamente um trigger, restrito a branch_includes: ["main"]. Nenhum build dispara pra nada além de main, isso nunca foi um caso de builds rodando e falhando.

Eu vinha assumindo que havia um trigger só cuidando de builds de produção e de preview, trocando comandos com base na branch. O modelo do Cloudflare é diferente: no máximo dois triggers por Worker, um pra branch de produção, e opcionalmente um totalmente separado pra tudo o mais. A checkbox “Builds for non-production branches” do painel gerencia esse segundo trigger; não há campo no primeiro que amplie o escopo dele.

Meu primeiro instinto foi dar PATCH no branch_includes do trigger existente pra ["*"]. O gate de permissão da minha própria ferramenta bloqueou a tentativa, a API queria o objeto completo do trigger nesse PATCH, o que significava reenviar deploy_command, que ainda era o comando literal de produção wrangler deploy, agora anexado a um trigger que combinaria com toda branch. E não é risco hipotético, uma nota anterior da base de conhecimento deste mesmo projeto documentou que disparar manualmente um build contra uma feature branch através do trigger de produção faz deploy dessa branch direto pra produção, sem confirmação, sem dry run. Bom lembrete de que “só amplia o filtro” pode silenciosamente virar “faz deploy de todo push pra prod”.

O fix de verdade foi um segundo trigger: mesmo comando de build, branch_excludes: ["main"], e um comando de deploy que não consegue chegar em produção, npx wrangler versions upload em vez de wrangler deploy. versions upload cria uma nova versão do Worker e para por aí, nada é promovido pro tráfego ao vivo.

Vendo funcionar de verdade

Eu não queria confiar só na teoria. Dei push na branch do fix depois de criar o segundo trigger e puxei os logs do build direto da API do Cloudflare:

Executing user deploy command: npx wrangler versions upload --config wrangler.toml dist/server/entry.mjs
...
env.SESSION (c49871…)   KV Namespace
Worker Version ID: cd654a24-…

Build de preview de verdade, comando correto, SESSION vinculado ao id fixado sem erro de provisionamento. E um check-run Workers Builds: imperfectsystems-com apareceu no commit, completed/success, que é exatamente o sinal que estava faltando antes. Essa lacuna específica (nenhum check pré-merge em PRs abertos) já tinha me queimado uma vez: um PR agrupado do dependabot escondeu um bump de versão major do Tailwind porque não havia nada pra falhar no PR antes do merge. Deveria ter uma chance de verdade de pegar isso da próxima vez.

Conclusões

Um padrão “útil” de um adapter de framework (suporte a sessão, aqui) pode injetar requisitos de infraestrutura que você nunca pediu, vale a pena ler o que sua ferramenta de build registra no log, não só o que ela produz. “Preview” é uma palavra sobrecarregada: preview_id no wrangler.toml é sobre wrangler dev, não sobre os deploys de preview do Workers Builds do Cloudflare, sistemas diferentes, mesma palavra. Quando uma checagem de permissão bloqueia uma ação, isso não é atrito pra contornar; essa aqui pegou um plano que teria silenciosamente reanexado um comando de deploy de produção a um filtro de branch coringa. E eu não confio numa mudança de config de CI/CD até ter visto um build de verdade rodar através dela e lido os logs, dry runs locais acertaram a forma, mas só o build ao vivo provou o fix.