← Voltar para o blog

Publicado em

Como funcionam os Ambientes de Preview da Zenifra para cada pull request?

Um Ambiente de Preview é uma cópia temporária do seu projeto HTTP, com URL própria, que roda a versão de um pull request sem tocar na aplicação principal. Na Zenifra, projetos com origem GitHub ou Forgejo criam e atualizam o preview a cada push no pull request e o removem quando ele é fechado ou quando o prazo de expiração vence, com cobrança por hora em real pelo preço do plano do projeto.

O que é um Ambiente de Preview na Zenifra

Um Ambiente de Preview é uma cópia temporária do seu projeto HTTP, com URL própria, que roda a versão de um pull request sem tocar na aplicação principal. Na Zenifra, ele nasce quando o pull request é aberto, é atualizado a cada push e é removido quando o pull request fecha ou quando o prazo de expiração vence.

A documentação define o preview como uma capacidade temporária de execução do projeto principal, com ciclo de vida, storage e cobrança próprios e uma URL quando a exposição do projeto permitir. Na prática, isso resolve um problema conhecido de qualquer time que revisa código: o revisor lê o diff, mas não vê a mudança funcionando. Com o preview, quem revisa abre um endereço, clica no fluxo alterado e comenta no pull request com base no que viu, e não no que imaginou.

Há dois caminhos para criar previews. O nativo serve a projetos com origem em repositório GitHub ou Forgejo e não exige workflow, API Key nem imagem no repositório: a Zenifra recebe os eventos do pull request e constrói o commit com o runtime e os comandos que o projeto já usa. O segundo caminho é a GitHub Action oficial da Zenifra, para quem já constrói uma imagem de container no CI e quer operar o preview de forma explícita, inclusive em projetos que não têm origem GitHub.

Um ponto que define o resto deste guia: o preview não é uma cópia dos dados de produção. Ele herda as variáveis de ambiente do projeto principal, então pode apontar para o mesmo banco, a mesma fila ou o mesmo bucket, e começa com armazenamento vazio. Entender essa herança é o que separa um preview útil de um preview que escreve em dados reais sem querer.

Como o Preview funciona por pull request

No fluxo nativo, você escolhe uma branch de destino, por exemplo main. Pull requests criados no próprio repositório do projeto e direcionados a essa branch participam do fluxo; os eventos opened, reopened e synchronize criam ou atualizam o preview identificado por pr-<número>. O evento edited reavalia o pull request quando a branch de destino muda, criando, atualizando ou removendo o preview conforme a nova elegibilidade, e closed remove o preview correspondente.

Ficam de fora pull requests destinados a outra branch e pull requests vindos de forks. Pull requests que já estavam abertos antes da ativação não são importados automaticamente; eles passam a contar no próximo evento relevante, como um novo push. Cada pull request mantém a mesma identidade entre atualizações, e reabrir um pull request com a mesma chave recria ou reativa a mesma identidade lógica, mantendo a URL sempre que possível.

A escolha da branch de destino dos previews é independente da forma de atualização principal. Ela define quais pull requests ganham preview e não muda a branch usada para atualizar a aplicação principal, que continua com a sua própria versão enquanto o preview é criado ou atualizado. No GitHub, quando o preview de um pull request aberto com os previews automáticos ativos fica disponível, a Zenifra publica um único comentário no pull request com o endereço e o tempo de vida; pushes seguintes não repetem o comentário.

Por trás, cada operação passa por estados públicos que você pode acompanhar: accepted, reserving, provisioning e updating até chegar a available em uma criação ou atualização, e deleting até deleted em uma remoção; failed encerra a operação com uma mensagem pública. Entregas duplicadas e retries idempotentes são seguros: a mesma chave reaproveita o mesmo ambiente e não cria cópias.

Como ativar os previews no Console, passo a passo

O projeto principal precisa estar em um plano que ofereça Ambientes de Preview. Em projetos GitHub, a conta GitHub precisa estar conectada à organização e o repositório acessível ao projeto. Em projetos Forgejo, a conexão precisa usar um token com write:repository e uma conta que administre os hooks do repositório, porque é o hook que entrega os eventos de pull request.

No GitHub há um detalhe de permissão que costuma passar despercebido: o GitHub App Zenifra precisa da permissão Pull requests (leitura e escrita) para receber os eventos e comentar o endereço. Instalações feitas antes dessa permissão continuam publicando a aplicação principal, mas não criam previews até alguém aprovar a atualização no GitHub. Instalações que aprovaram só a leitura criam previews normalmente, sem o comentário no pull request.

Para aprovar, uma pessoa com acesso de administração à conta ou à organização abre as configurações do GitHub em GitHub Apps (em contas pessoais, Applications e depois Installed GitHub Apps), escolhe Configure no app Zenifra e, no aviso de atualização, Review request e Accept new permissions. Depois disso, o próximo evento do pull request, como um novo push, cria ou atualiza o preview; o comentário com o endereço vale para pull requests abertos depois da aprovação.

  • Abra a seção Ambientes de Preview na página do projeto principal e escolha Configurar previews.
  • Ative Habilitar Ambientes de Preview.
  • Ative Habilitar previews automáticos do GitHub (ou Habilitar previews automáticos do Forgejo).
  • Escolha a Branch de destino dos previews, por exemplo main.
  • Defina Expiração padrão (horas), Expiração máxima (horas) e Limite de ambientes ativos neste projeto.
  • Abra ou atualize um pull request para essa branch e acompanhe a criação do preview.

Configurar previews exige a permissão project.preview.configure, por sessão de usuário ou API Key da organização. Se você desativar os previews automáticos ou os Ambientes de Preview, trocar a branch de destino ou desconectar o repositório, os previews nativos afetados são removidos e as publicações pendentes deixam de valer. A aplicação principal não é afetada por essa limpeza.

URLs temporárias, expiração e limpeza automática

Cada preview tem o próprio endereço, separado da URL de produção. A demonstração ilustrativa da página Preview mostra a aplicação principal em https://loja.clients.zenifra.com e o preview do pull request 2 em https://loja-pr-2.clients.zenifra.com, com dados fictícios. Use sempre o endereço publicado no comentário do pull request ou mostrado no Console e na API como fonte de verdade, porque a URL é devolvida quando o preview fica disponível.

O tempo de vida (TTL) padrão é de 24 horas e pode ser configurado entre 1 hora e 168 horas, ou seja, até 7 dias depois da última atualização. Uma criação ou atualização bem-sucedida renova a expiração; entregas duplicadas e retries não estendem o prazo só por se repetirem. Se o workflow de fechamento não rodar, a Zenifra remove previews expirados automaticamente, inclusive os que estiverem parados.

A limpeza acontece em quatro situações: o pull request é fechado (fluxo nativo), a expiração vence, o projeto principal é excluído (todos os previews somem na mesma hora) ou você desativa o recurso, troca a branch de destino ou desconecta o repositório. Na remoção, a cobrança de compute e de storage termina no instante da remoção, e o endereço do preview é liberado.

Os ambientes ativos têm limite em dois níveis, e vale o menor deles. Uma organização pode ter até 10 previews ativos ao mesmo tempo, e um projeto principal, até 2. Criar além do limite termina a operação como failed, com mensagem pública; a Action encerra o job com falha. Para ampliar o limite da organização, a documentação orienta enviar um e-mail para support@zenifra.com com o nome e o e-mail de acesso da organização, o uso atual e o limite desejado, com o motivo.

RegraValor documentado
Expiração padrão (TTL)24 horas
Faixa de TTL configurável1 a 168 horas (7 dias)
Previews ativos por organizaçãoaté 10 ao mesmo tempo
Previews ativos por projeto principalaté 2 ao mesmo tempo
Chave do preview1 a 100 caracteres (A-Z, a-z, 0-9, ., _ e -), com ao menos uma letra ou número
Chave padrão em pull requestpr-<número>
Espera máxima da Action (WAIT_TIMEOUT)1s a 15m, padrão 10m

Variáveis, banco e armazenamento no Preview

Todo preview herda, dentro da plataforma, as variáveis configuradas no projeto principal, em cada criação ou atualização. Os valores nunca são expostos pela API, pelo Console ou pela Action, e nunca aparecem nos outputs, no Job Summary nem nos logs. Variáveis gerenciadas pela Zenifra são regeneradas para o preview. O preview também herda porta, exposição e regras de acesso necessárias para rodar a aplicação, além do plano.

A consequência é direta: se a DATABASE_URL do projeto principal aponta para o banco de produção, o preview também aponta. O mesmo vale para filas, buckets e APIs externas. A página Preview responde isso sem rodeios: o Preview não cria cópia do banco, e variáveis herdadas podem apontar para o mesmo banco, fila ou serviço. Uma migration destrutiva rodando no start do preview, ou um teste que cria pedidos, atinge os dados reais.

O que não é herdado nem criado hoje: dados de bancos, filas, buckets e outros serviços; domínios personalizados; e comandos customizados de inicialização da imagem. O storage do preview é novo e começa vazio. Se a aplicação depende de dados iniciais, planeje dados de teste ou uma fonte segura para a validação.

Um padrão que funciona com essas regras é ativar os previews em um projeto de homologação, e não no projeto de produção. Você cria um segundo projeto HTTP a partir do mesmo repositório, com variáveis apontando para um banco gerenciado de testes, e liga os Ambientes de Preview nele. Os previews herdam as variáveis desse projeto e escrevem só no banco de testes. Quando a mudança é aprovada e o merge acontece, o projeto de produção publica pela forma de atualização que você já usa. Somado a migrations compatíveis com duas versões da aplicação, isso mantém produção fora do alcance dos testes.

Previews a partir de uma imagem com a GitHub Action

Se o seu CI já gera uma imagem de container, a GitHub Action oficial zenifra/action-zenifra-deploy cria, atualiza e remove previews de forma explícita. Esse fluxo é independente do nativo e funciona inclusive em projetos sem origem GitHub. A Action precisa da API Key da organização guardada em um secret do GitHub e de uma imagem pronta, normalmente exposta como variável do repositório ou da organização.

Em um evento pull_request, a Action usa pr-<número> como chave quando PREVIEW_KEY não é informado; fora de pull requests, a chave é obrigatória. Com PREVIEW_ACTION=auto, um pull request fechado aciona a remoção, e nesse caso a imagem pode ser omitida. A Action aguarda o estado available em um upsert e deleted em uma remoção e devolve os outputs preview_id, preview_url, expires_at, operation_id e preview_status. O preview sempre usa o plano do projeto principal: não existe PREVIEW_PLAN nem preço separado.

A chave mínima é limitada ao projeto principal: project.read para consultar o projeto, project.preview.read para listar, project.preview.deploy junto com project.env.read (ou project.image.update) para criar ou atualizar, e project.preview.delete para remover. Sem a leitura de variáveis, a criação retorna PREVIEW_ENV_ACCESS_REQUIRED, porque o preview herda as variáveis. Use só um fluxo por chave: se um preview nativo já usa pr-<número>, a Action recebe GITHUB_PREVIEW_KEY_OWNED, e o contrário bloqueia o run nativo.

  • name: Zenifra preview
  • on: pull_request com types: [opened, synchronize, reopened, closed]
  • permissions: contents: read
  • uses: zenifra/action-zenifra-deploy@v0.0.5
  • with: PROJECT_ID: ${{ vars.ZENIFRA_PROJECT_ID }}, API_KEY: ${{ secrets.ZENIFRA_API_KEY }}, IMAGE: ${{ vars.ZENIFRA_PREVIEW_IMAGE }}
  • with: PREVIEW: true, PREVIEW_ACTION: auto, PREVIEW_TTL: 24h, WAIT_TIMEOUT: 10m

Para testar uma branch ou versão fora de um pull request, a documentação traz um workflow com workflow_dispatch, em que você informa preview_key e escolhe upsert ou delete. Não reaproveite a mesma chave para mudanças que precisam existir ao mesmo tempo: cada chave é um único ambiente lógico.

Quanto custa um Ambiente de Preview

O preview usa o plano do projeto principal e é cobrado por hora, em real, enquanto estiver ativo. O preço horário vem do catálogo público do plano; não existe catálogo de planos exclusivo para Preview, e o modo de pagamento do preview é sempre por hora, mesmo que o projeto principal esteja em contrato mensal ou anual. A calculadora estima o custo como quantidade de previews multiplicada pelas horas ativas de cada um e pelo preço horário do plano.

Os números abaixo usam o catálogo de https://api.zenifra.com/v1/project/plans consultado em 06/11/2026, em que os preços vêm em centavos: Static 1 (R$ 0,01/h), Basic 5 (R$ 0,05/h), Premium 11 (R$ 0,11/h) e Premium Plus 22 (R$ 0,22/h). A conta de um preview que vive 24 horas no Basic é 24 × R$ 0,05 = R$ 1,20. Um preview que dura a semana inteira, no TTL máximo de 168 horas, custa 168 × R$ 0,05 = R$ 8,40. Um time que abre 10 pull requests no mês, cada um com preview ativo por 30 horas, soma 300 horas: 300 × R$ 0,05 = R$ 15,00.

Dois cuidados mantêm a conta previsível. O primeiro é o TTL: um preview esquecido vive até a expiração, então um prazo curto, como o padrão de 24 horas, limita o custo de pull requests parados. O segundo é o limite de ambientes ativos do projeto, que você define no Console e que nunca passa de 2 por projeto. A API de custos dos previews devolve valores acumulados por snapshots horários, o valor pendente e uma estimativa até a expiração, que não é cobrança final.

Se a organização tiver pagamentos pendentes, a criação de previews retorna ORGANIZATION_BILLING_BLOCKED até a regularização. O custo do preview sai do mesmo crédito da organização usado por aplicações, bancos e IA, pago em real por PIX ou boleto, com o cartão como reserva para cobranças pós-pagas.

Plano do projeto (preço/h)1 preview por 24 h1 preview por 168 h300 horas de preview no mês
Static (R$ 0,01/h)R$ 0,24R$ 1,68R$ 3,00
Basic (R$ 0,05/h)R$ 1,20R$ 8,40R$ 15,00
Premium (R$ 0,11/h)R$ 2,64R$ 18,48R$ 33,00
Premium Plus (R$ 0,22/h)R$ 5,28R$ 36,96R$ 66,00
Business (R$ 0,86/h)R$ 20,64R$ 144,48R$ 258,00

Os valores consideram um ambiente por vez, como a calculadora, e cobrem o processamento. O storage do preview tem cobrança própria, que também termina no instante em que o preview é removido.

Fluxo de revisão em time e permissões

O ganho real do Preview aparece no fluxo de revisão. Quem abre o pull request não precisa mandar print nem gravar vídeo: o comentário da Zenifra traz o endereço e o prazo. Quem revisa abre a URL, testa o fluxo, volta ao pull request e pede ajustes; cada push atualiza o mesmo preview, com a mesma identidade. Produto, design e atendimento podem validar a mudança sem instalar nada, desde que tenham o endereço.

Na Zenifra, cada pessoa entra com o próprio login na organização, com papéis owner, assistant ou member e permissões por recurso e ação, com escopo por projeto. Para previews, as permissões são separadas: project.preview.read para consultar, project.preview.deploy para criar e atualizar, project.preview.delete para remover e project.preview.configure para mudar as configurações. Assim dá para liberar a consulta e a publicação de previews sem dar acesso a faturamento.

Não há promoção automática do Preview para a aplicação principal. Depois de validar, a versão chega à produção pelo fluxo configurado no projeto principal: com Automático por branch, o merge na branch publica; com Por Tag ou Por Release, a tag ou a release publicam. Isso mantém um único caminho para produção e evita que um ambiente de teste vire produção por engano.

AçãoPermissão mínima no projeto principal
Consultar o projeto principalproject.read
Listar previews e ver detalhesproject.preview.read
Criar ou atualizar previewproject.preview.deploy e project.env.read (ou project.image.update)
Remover previewproject.preview.delete
Alterar as configurações de Previewproject.preview.configure

Comparação com Vercel, Render, Railway e Heroku

As quatro plataformas têm ambientes por pull request, com modelos diferentes. A tabela resume o que as páginas oficiais dizem, consultadas em 06/11/2026. A Vercel cria Preview Deployments em todo push para uma branch que não é a de produção, em pull requests e no CLI sem --prod, com URL por branch e por commit, e cada ambiente pode ter variáveis próprias. O Render recria serviços, datastores e grupos de variáveis por pull request no plano de workspace Pro ou superior, sem copiar os dados. A Railway cria um ambiente temporário por pull request, removido no merge ou no fechamento. O Heroku usa Review Apps, que dependem de Pipelines, integração com o GitHub e um app.json.

A diferença mais relevante para quem testa com dados é o banco. Render e Heroku criam datastores e add-ons novos para cada preview e oferecem ganchos de inicialização para popular dados de teste; nenhum dos dois copia o conteúdo do banco principal. Na Zenifra, o preview não cria banco: herda as variáveis e, se nada mudar, aponta para o mesmo banco do projeto principal. Isso é mais simples e não gera custo extra de banco, mas pede o cuidado da seção sobre variáveis.

Quando outra opção serve melhor: se você precisa de um banco novo e isolado por pull request, criado automaticamente, Render e Heroku fazem isso hoje. Se o projeto é um frontend estático ou serverless e o time já vive na Vercel, os Preview Deployments dela cobrem o caso sem servidor rodando. A Zenifra faz mais sentido quando a aplicação é um servidor HTTP completo, a cobrança precisa ser em real e o mesmo console já hospeda a aplicação e o banco.

PlataformaComo o ambiente é criadoBanco e dadosRemoçãoCobrança
ZenifraAutomático por PR do próprio repositório para a branch escolhida (GitHub ou Forgejo) ou pela Action com imagemHerda variáveis; não cria nem copia banco; storage começa vazioPR fechado, TTL (24 h padrão, até 168 h) ou exclusão do projetoPreço por hora do plano do projeto, em real
VercelPush em branch que não é a de produção, PR ou CLI sem --prodVariáveis de Preview próprias, inclusive por branchRetenção padrão de 30 dias para deployments de pré-produção (Hobby e Pro)Deployments retidos contam como Deployment Storage
RenderPreview Environments por PR (manual ou automático), exige workspace Pro ou superiorCria cópias de serviços e datastores sem os dadosMerge ou fechamento do PR; expireAfterDays opcional, sem expiração por padrãoIgual aos demais serviços, proporcional ao segundo
RailwayPR environments ativados em Project Settings, EnvironmentsAmbiente temporário por PR; Focused PR Environments em monoreposMerge ou fechamento do PRModelo por uso: RAM US$ 10/GB-mês, CPU US$ 20/vCPU-mês
HerokuReview Apps automáticos ou manuais; exigem Pipelines, GitHub e app.jsonNão copia o banco; seed com o script postdeployFechamento do PR (os automáticos) e opção de 1, 2, 5, 14 ou 30 dias de inatividadeDynos e add-ons como apps normais, proporcional ao segundo

O Preview copia o banco de produção?

Não. O preview não cria nem copia banco: ele herda as variáveis do projeto principal, então pode apontar para o mesmo banco, fila ou serviço. Revise esses valores antes de testar, para que uma mudança não escreva em dados compartilhados.

Para isolar os testes, ative os previews em um projeto de homologação cujas variáveis apontem para um banco de testes. O armazenamento do preview começa vazio, então planeje dados iniciais quando a aplicação depender deles.

Pull requests de forks ganham Preview?

Não no fluxo nativo. Só pull requests criados no próprio repositório do projeto, com destino à branch escolhida, criam preview; forks e pull requests para outras branches ficam de fora, tanto no GitHub quanto no Forgejo.

Pull requests que já estavam abertos antes da ativação também não são importados de imediato: eles passam a contar no próximo evento relevante, como um novo push.

Quanto tempo um Preview fica no ar?

Até o pull request ser fechado ou até a expiração vencer, o que acontecer primeiro. O padrão é 24 horas, configurável entre 1 e 168 horas, e cada atualização bem-sucedida renova o prazo.

Previews expirados são removidos automaticamente, inclusive os parados, e a cobrança de compute e storage termina no instante da remoção. Excluir o projeto principal remove todos os previews dele na mesma hora.

Qual é o plano mais barato para usar Ambientes de Preview?

O menor plano HTTP no catálogo é o Static, a R$ 0,01 por hora, pensado para servidores HTTP leves; para aplicações Node.js, a documentação recomenda o Basic, a R$ 0,05 por hora. O preview herda o plano do projeto principal, então não existe preço separado.

Um preview de 24 horas custa R$ 0,24 no Static e R$ 1,20 no Basic. O projeto principal precisa estar em um plano compatível com previews; se não estiver, a API retorna preview_plan_not_allowed.

Como a versão aprovada vai para produção?

Pelo fluxo configurado no projeto principal, não pelo preview. Não há promoção automática do Preview para a aplicação principal: com Automático por branch, o merge publica; com Por Tag ou Por Release, a tag ou a release que corresponder ao padrão publicam.

Depois do merge, o fechamento do pull request remove o preview nativo. Acompanhe a build da produção em Logs de build e valide a aplicação na URL pública.

Simular o custo de previews na calculadora

Respeitamos sua privacidade

Usamos cookies essenciais para o funcionamento do site. Cookies de medição e marketing, como Google Ads, só serão ativados se você aceitar todos. Consulte nossa política de cookies.