Wrangler Cloudflare: controle o deploy de cada cliente

Os quatro papéis de Worker da Cloudflare agora permitem delimitar por cliente uma credencial compartilhada de deploy, inclusive em fluxos com Wrangler Cloudflare. Desde 15 de setembro de 2026, uma agência consegue permitir que o job de CI de um cliente faça deploy em um Worker existente sem também conceder direito de exclusão nem acesso a todos os outros Workers da conta — desde que nenhuma política mais ampla expanda esse acesso.

O ganho real está no escopo

Toda permissão combina duas coisas. O papel define o que alguém pode fazer; o escopo, onde essa ação é permitida.

A Cloudflare agora permite associar um papel de Worker ao escopo de um Worker específico para um membro da equipe, User Group, agente ou token de API. O mesmo papel ainda pode abranger todos os Workers, mas essa deixou de ser a única opção.

À primeira vista, parece apenas mais um ajuste administrativo. Para um estúdio ou uma agência que mantém vários clientes na mesma conta da Cloudflare, porém, o handoff muda de figura: a credencial de deploy do Cliente A pode parar no Worker do próprio Cliente A.

O lançamento de 15 de setembro está disponível para todos os clientes e funciona pelo dashboard, pela API ou pelo Terraform.

Este é o conjunto completo de papéis descrito na referência de papéis do Workers:

Essa separação faz sentido porque depurar, revisar código, publicar código e excluir o serviço são trabalhos diferentes. Não há motivo para todos herdarem a mesma credencial.

As permissões anteriores do Workers valiam para a conta inteira. O novo modelo pode ser aplicado à Developer Platform, a todos os Workers ou a um Worker existente. Uma política do Workers no nível do produto abrange todos os Workers atuais e futuros; uma política por Worker alcança somente os que forem selecionados.

Existe uma limitação estrutural: não é possível dar acesso específico a um Worker que ainda não existe. Criar um novo Worker continua exigindo Admin no nível do produto.

O que muda no handoff para o cliente

Imagine uma agência pequena que hospeda um Worker para cada cliente. O fluxo de deploy precisa publicar novas versões de client-a-api, mas não precisa criar Workers, excluir esse Worker nem tocar em client-b-checkout.

Antes desse lançamento, as permissões comuns de CI para Workers — que a Cloudflare agora classifica como legadas — valiam para toda a conta. Restavam duas opções claras: aceitar uma credencial ampla ou separar o cliente em outra conta. O escopo por Worker abre uma terceira via: preservar a estrutura da conta e conceder Editor ao token de deploy somente em client-a-api.

A equação da assinatura não muda, pois os controles por Worker estão disponíveis para todos os clientes. A equação operacional, sim.

Esse modelo deixa de fora uma troca importante. Doze credenciais com escopo por cliente significam mais segredos para emitir, guardar e rotacionar do que uma única credencial compartilhada. O benefício não está em ter menos credenciais, mas em reduzir o conjunto de projetos que precisa ser investigado quando uma delas falha ou vaza.

Um fundador solo, com apenas um Worker e sem acesso de deploy compartilhado, mal perceberá a mudança. O mesmo vale para uma equipe que dá deliberadamente ao grupo de plataforma o controle de todos os Workers. O recurso faz diferença quando várias pessoas, clientes ou tarefas automatizadas dividem uma conta da Cloudflare, mas não deveriam dividir o mesmo raio de impacto.

Wrangler Cloudflare: o acesso certo para o deploy de cada cliente

O ponto de partida mais simples para o handoff é um Worker existente, com Route ou Custom Domain estável. Assim, a criação do Worker e as mudanças de domínio ficam fora do job de deploy.

1. 1

   Defina a tarefa antes de escolher o papel

   Comece com uma frase: “Este fluxo faz deploy de novas versões do Worker client-a-api existente.”

   Essa descrição leva ao papel Editor no escopo do Worker individual. Se o job precisar criar um Worker, será necessário Admin no nível do produto. Se também precisar adicionar, alterar ou remover uma Route ou um Custom Domain, será preciso Workers Routes Write para cada zona afetada.

2. 2

   Crie um token de API pertencente à conta

   Na Cloudflare, acesse Manage Account > Account API Tokens e crie um token pertencente à conta. Defina o escopo como Specified Workers, escolha client-a-api e selecione Editor.

   Para o fluxo, use um token pertencente à conta, não o token de usuário de uma pessoa. A Cloudflare apresenta esses tokens como service principals para integrações duradouras; desse modo, o deploy não para quando quem criou a credencial deixa a empresa. Criar ou atualizar um deles exige a permissão Super Administrator.

3. 3

   Execute o Wrangler com esse token

   Guarde o token no cofre de segredos do sistema de deploy. A Cloudflare documenta estas variáveis de ambiente para o Wrangler:

   export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
   export CLOUDFLARE_ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
   npx wrangler deploy

   Execute o comando no projeto configurado para o Worker existente. wrangler login não substitui esse processo, pois o fluxo OAuth ainda não oferece suporte a autorização granular.

4. 4

   Faça a migração e remova o acesso amplo

   Publique uma versão inofensiva com o novo token e confirme que o Worker pretendido foi atualizado. Verifique também se o token não tem papel do Workers no nível do produto nem escopo sobre recursos alheios ao projeto.

   Depois, retire desse fluxo o segredo antigo de deploy amplo. Manter as duas credenciais durante o teste é sensato; mantê-las depois do teste anula o limite que acabou de ser criado.

Esse é todo o handoff necessário para um deploy rotineiro. Como essas ações estão dentro do papel Editor, o job do cliente pode atualizar, enviar, publicar, reverter e renomear o Worker, além de gerenciar seus segredos. Ele não pode excluir o Worker, e a política por Worker não abre acesso aos demais Workers.

Quatro tarefas, quatro políticas que fazem sentido

Um agente de suporte que só precisa reunir evidências

Dê a um agente de depuração o papel Metadata Read-Only no Worker afetado. Ele poderá consultar configurações, métricas, logs e traces sem ler o código-fonte nem alterar o serviço.

O resultado é um fluxo de suporte capaz de coletar evidências sem virar, silenciosamente, um fluxo de revisão de código ou de deploy. O mesmo papel basta para usar wrangler tail nesse Worker.

Um desenvolvedor externo que revisa o projeto de um cliente

Conceda Content Read-Only ao prestador no Worker do cliente. Assim, ele pode inspecionar o código publicado e as configurações, mas não consegue modificar o Worker nem fazer deploy.

O ganho é um limite de revisão mais claro. Não é preciso conceder Editor só porque o revisor precisa entender o que está em execução.

Um pipeline de CI exclusivo para o cliente

Conceda ao token pertencente à conta o papel Editor em um único Worker existente. Ele poderá publicar e reverter versões sem excluir o Worker nem alcançar outros Workers.

Esse é o melhor encaixe para o handoff de uma agência, porque a credencial pertence ao fluxo, não a um funcionário. Se você também usa agentes de navegador nos projetos de clientes, os controles de hosts aprovados da Cloudflare resolvem outra metade desse limite: aonde o navegador pode ir. Este lançamento controla qual Worker a identidade de deploy pode alterar.

Um responsável pela plataforma que cuida do ciclo de vida

Reserve Admin para a pessoa ou automação que realmente precise excluir recursos. Mantenha Admin no nível do produto com o responsável por criar Workers e, depois, entregue o Worker pronto às políticas mais restritas do dia a dia.

O benefício é separar de forma visível o trabalho de ciclo de vida da entrega rotineira. Um job de deploy não precisa da mesma autoridade de quem cria e aposenta os serviços dos clientes.

O limite ficou menor, mas ainda não é isolamento completo

O principal benefício é real, porém resumir tudo a “apenas um Worker” pode levar a uma conclusão perigosa.

Os Durable Objects exigem o mesmo cuidado. Eles não têm papéis ou escopos independentes: herdam o acesso do Worker que os implementa. Metadata Read-Only inclui métricas, logs e traces dos Durable Objects sem acesso aos dados armazenados, mas Editor também atinge o nível de permissão documentado para usar o Data Studio a fim de consultar ou modificar dados em um Durable Object baseado em SQLite.

Routes formam outro limite independente. Editor basta para publicar uma nova versão quando uma Route ou um Custom Domain existente permanece igual. Alterar essa conexão também exige Workers Routes Write em cada zona afetada. A Cloudflare informa ainda que Custom Domains não oferecem suporte a papéis por Worker no momento.

Por fim, as permissões da Cloudflare são cumulativas. Uma política direta e restrita não anula outra, mais ampla, herdada por meio de um User Group. A tela Members mostra permissões diretas; as políticas herdadas de grupos precisam ser verificadas na aba Groups. Sem essa checagem, a interface pode exibir a política restrita desejada enquanto o conjunto efetivo de permissões continua amplo.

Quem deve agir agora

Vale agir ainda nesta semana se uma conta reúne Workers de vários clientes e alguma pessoa, agente ou tarefa de CI ainda carrega permissão para todos eles ao executar um trabalho limitado a um só. O benefício aparece com mais clareza quando o Worker já existe e suas conexões de domínio não mudam nos deploys rotineiros.

Espere antes de restringir o token se o fluxo cria Workers, altera Routes ou Custom Domains ou depende de acesso direto a produtos de dados vinculados. Primeiro, mapeie essas ações; caso contrário, o próximo deploy pode falhar no meio do caminho.

Nada muda para quem nunca compartilha acesso a Workers, opera apenas um Worker ou mantém o deploy intencionalmente nas mãos de uma equipe de plataforma com responsabilidade sobre a conta inteira.

A ação para segunda-feira

Comece mudando a política de permissão por trás do deploy de CI de um cliente existente. Configure um token pertencente à conta como Editor, restrinja-o àquele Worker, liste todos os bindings e Durable Objects herdados que ele pode afetar, confira as políticas diretas e de grupo e, por fim, faça o deploy sem alterar a Route nem o Custom Domain.

Quando esse teste passar, remova o segredo antigo que alcançava todos os Workers. Essa única migração cria um limite real e um padrão que pode ser repetido com o próximo cliente.

Se quiser acompanhar mais análises operacionais de mudanças em plataformas, em linguagem direta, assine a newsletter.