Builds e deploy pelo GitHub na Cloudflare
O Workers Builds é a integração da Cloudflare com o GitHub e o GitLab que constrói e publica um Worker a cada push no repositório ligado. Ele roda o comando de build e depois o npx wrangler deploy num ambiente da Cloudflare, por isso o commit na branch de produção vira uma versão nova do site sem que você publique nada da sua máquina.
Ficha e sumário da página
- Referência técnica
- Wrangler 4.162.0
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Do push à versão ativa
O Workers Builds liga um Worker a um repositório do GitHub, do GitLab ou do Artifacts da Cloudflare. Na primeira ligação, você autoriza o aplicativo da Cloudflare no GitHub e escolhe o repositório. Depois disso, cada commit enviado dispara um build, com um resultado que depende da branch. A documentação descreve o processo em duas etapas: o comando de build, opcional, compila o projeto antes que o comando de deploy publique o Worker.
Push no GitHub
git push origin mainO commit chega à branch que a Cloudflare acompanha, a main por padrão.
Comando de build
npm run buildCompila o projeto num ambiente com 2 vCPU e 8 GB de memória no plano Free.
Comando de deploy
npx wrangler deployEnvia o código e os assets com a versão do Wrangler fixada no package.json.
Versão ativa
Version HistoryA versão nova aparece no histórico e assume o tráfego do Worker.
O comando de deploy padrão, npx wrangler deploy, roda com a versão do Wrangler declarada no package.json do projeto. Por isso uma atualização do Wrangler entra no deploy pelo mesmo commit que altera o arquivo, sem mudança no painel. O comando também aceita um script do próprio projeto, como npm run deploy.
O build falha quando o nome do Worker no painel difere do campo name do arquivo de configuração do Wrangler na pasta raiz informada. A documentação usa essa conferência para garantir que o Worker publicado pelo repositório é o mesmo Worker cadastrado no painel.
Prévias por branch
As branches que não são a de produção rodam o comando de prévia, que por padrão é o npx wrangler preview. Ele cria ou atualiza uma prévia sem promover nada para produção. A URL da prévia aparece na seção de prévias do Worker. Os provedores suportados podem publicar essa URL num comentário do pull request.
O Pages segue um fluxo parecido com outros nomes, no qual cada branch fora da produção gera um deploy de prévia com um endereço fixo de hash, como 373f31e2.meu-site.pages.dev. O alias com o nome da branch, como development.meu-site.pages.dev, acompanha o deploy mais recente dela. A integração do Pages também publica o status do build no GitHub e aceita pular o build pela mensagem do commit.
Workers Builds
- Publica um Worker, com ou sem assets estáticos.
- Roda o comando de build e o comando de deploy, por padrão
npx wrangler deploy. - Cria uma versão no histórico a cada build da branch de produção.
- Liga repositórios do GitHub, do GitLab e do Artifacts da Cloudflare.
Integração do Pages
- Publica um projeto do Pages a partir da pasta de saída.
- Roda o comando de build e envia a pasta configurada, como
dist. - Cria um deploy de produção ou de prévia a cada push.
- Liga repositórios do GitHub e do GitLab, sem instâncias próprias desses serviços.
Repositório com vários projetos
A pasta raiz é uma configuração opcional do build. Ela diz onde o comando de build roda e serve para monorepos, porque permite ligar um Worker a uma pasta específica do repositório. Um repositório com o site e a API em pastas separadas liga cada pasta a um Worker próprio, cada um com o seu arquivo de configuração do Wrangler.
O token que autoriza o envio e o deploy também fica fora do repositório. Por padrão, a Cloudflare gera automaticamente um token de API no seu cadastro quando você usa o Workers Builds e o reaproveita nos builds seguintes. Você também pode informar um token próprio nas configurações do build.
Limites do build
- 3.000 minutos por mêsOs planos pagos têm 6.000 minutos e cobram US$ 0,005 por minuto extra.
- Um build por vezOs planos pagos rodam seis builds simultâneos.
- 20 minutos por buildO build que passa desse tempo é encerrado, em qualquer plano.
- 90 dias de históricoOs builds e os logs ficam disponíveis por 90 dias.
O Pages tem outra tabela no plano Free: 500 builds por mês, um por vez, com o mesmo tempo máximo de 20 minutos. Como o Pages faz um build a cada push, os commits nas branches de prévia também consomem esses 500 builds mensais.
O deploy do website da Promovaweb
O website da Promovaweb sai do GitHub para a Cloudflare por esse caminho. Segundo o README do projeto, a publicação começa no GitHub: depois das validações, o commit vai para a branch main, onde a integração do provedor o recebe e publica o site. O mesmo documento proíbe rodar wrangler deploy na máquina local e trata o preview local só como desenvolvimento.
O build gera a pasta dist do Astro, que o deploy publica como assets estáticos do Worker promovaweb-website, com o arquivo src/worker.mjs aplicando os redirecionamentos permanentes. A página Cloudflare Workers mostra o arquivo de configuração desse Worker. A página DNS e domínios explica como o domínio chega até ele.