Ambientes de Preview

Um Ambiente de Preview é uma capacidade temporária de execução do seu projeto HTTP, com ciclo de vida, storage e cobrança próprios e uma URL quando a exposição permitir. Use-o para revisar uma mudança sem substituir a aplicação principal.

Projetos HTTP com origem em um repositório GitHub ou Forgejo podem criar previews automaticamente para pull requests, sem workflow, API Key ou imagem configurada no repositório. A GitHub Action da Zenifra continua disponível para o fluxo em que você já constrói uma imagem e quer operar o preview explicitamente.

Permissões necessárias

A chave mínima para o ciclo operacional do Preview é limitada ao projeto principal:

A configuração inicial de Preview exige uma sessão de usuário autorizada com project.preview.configure; ela não faz parte da chave mínima da Action. owner tem acesso completo; assistant, member e API Keys precisam dos grants correspondentes.

Antes de começar

1. Tenha um projeto HTTP na Zenifra.
2. Se a origem do projeto for GitHub, confirme que a conta GitHub está conectada à organização e que o repositório está acessível ao projeto. Se for Forgejo, confirme que a conexão usa write:repository e uma conta que administre os hooks do repositório.
3. No console, abra a seção Ambientes de Preview do projeto principal, escolha Configurar previews e ative Habilitar Ambientes de Preview.
4. Para o fluxo nativo, ative Habilitar previews automáticos do GitHub ou Habilitar previews automáticos do Forgejo e escolha a Branch de destino dos previews.
5. Defina a Expiração padrão (horas), a Expiração máxima (horas) e o Limite de ambientes ativos neste projeto. O preview usa o plano do projeto principal.
6. Para o fluxo da Action, guarde a API Key da organização do projeto principal em um secret do GitHub e disponibilize uma imagem pronta em uma variável do repositório ou da organização.

PREVIEW=true não habilita a funcionalidade sozinho. O opt-in do projeto e os limites definidos no console são sempre aplicados antes de uma criação ou atualização.

Cada preview é cobrado por hora em BRL enquanto estiver ativo. O preço e os limites efetivos vêm do catálogo e das configurações do projeto; consulte o console antes de habilitar a funcionalidade.

Como a identidade funciona

A identidade de um preview é formada pela organização, pelo projeto principal e pela chave do preview. A mesma chave reaproveita o mesmo ambiente entre execuções e torna retries seguros.

• Em um evento pull_request, a Action usa pr-<number> quando PREVIEW_KEY não é informado.
• Fora de um pull request, PREVIEW_KEY é obrigatório.
• A chave aceita de 1 a 100 caracteres seguros (A-Z, a-z, 0-9, ., _ e -). Chaves inválidas são rejeitadas; não são corrigidas silenciosamente.
• pull_request com opened, synchronize ou reopened faz upsert do preview.
• pull_request.closed solicita a remoção imediata.
• Reabrir um pull request com a mesma chave recria ou reativa a mesma identidade lógica e mantém a URL sempre que possível.

Uma criação ou atualização bem-sucedida renova a expiração. Entregas duplicadas e retries idempotentes não estendem o TTL apenas por serem repetidos. O TTL padrão é de 24 horas e pode ser configurado entre 1 hora e 168 horas. Se o workflow de fechamento não for executado, a Zenifra remove previews expirados automaticamente.

Previews nativos para pull requests do GitHub e do Forgejo

O fluxo nativo usa o repositório e os comandos já configurados no projeto GitHub ou Forgejo. Depois que Ambientes de Preview e os previews automáticos do provedor estiverem habilitados, escolha uma branch de destino, como main. A escolha dessa branch é independente da forma de atualização principal: ela define quais pull requests criam previews e não altera a branch usada para atualizar a aplicação principal.

Para pull requests criados no próprio repositório do projeto:

• opened, reopened e synchronize criam ou atualizam o preview identificado por pr-<number> quando a branch de destino corresponde à branch escolhida;
• edited reavalia o pull request quando a branch de destino muda, criando, atualizando ou removendo o preview conforme a nova elegibilidade;
• closed remove o preview correspondente;
• pull requests destinados a outra branch não criam preview;
• pull requests de forks não participam do fluxo nativo;
• pull requests que já estavam abertos antes da ativação não são importados automaticamente; eles passam a ser considerados no próximo evento relevante.

No Forgejo, os eventos chegam pelo hook do repositório criado pela conexão; sem permissão para administrar hooks, os previews automáticos não podem ser habilitados.

Cada pull request mantém a mesma identidade de preview entre atualizações. A Zenifra usa a configuração de runtime e os comandos do projeto para construir o commit do pull request. O projeto principal continua com a sua própria versão enquanto o preview é criado ou atualizado.

O preview segue o plano, a exposição e as variáveis do projeto principal conforme o comportamento atual de Previews. Variáveis herdadas podem apontar para os mesmos serviços usados pela aplicação principal. O storage é novo e começa vazio para o preview; dados, domínios personalizados e comandos customizados de imagem não são herdados. Não trate o preview como uma cópia dos dados de produção.

Esse caminho não exige GitHub Action, API Key, IMAGE, PREVIEW_KEY ou configuração de workflow no repositório. Para construir uma imagem fora desse fluxo ou operar um preview com uma automação própria, use a GitHub Action descrita a seguir.

Atenção: use apenas um fluxo para a chave pr-<number> no mesmo projeto. Se um preview da Action já usar essa chave, o fluxo nativo não o substitui e o run nativo fica bloqueado.

Se você desabilitar os previews automáticos do provedor ou Ambientes de Preview, mudar a branch de destino ou desconectar/trocar o repositório do projeto, os previews nativos afetados são removidos e as publicações pendentes deixam de ser válidas. A aplicação principal e sua forma de atualização permanecem separadas dessa limpeza.

Permissão do GitHub App

Para receber os eventos de pull request, o GitHub App Zenifra precisa da permissão Pull requests (somente leitura). Instalações feitas antes dessa permissão continuam funcionando para deploys, mas não criam previews até que a atualização seja aprovada no GitHub:

1. Uma pessoa com acesso de administração à conta ou à organização abre as configurações no GitHub, em GitHub Apps (em contas pessoais, Applications > Installed GitHub Apps).
2. Em Zenifra, escolha Configure.
3. No aviso de atualização de permissões, escolha Review request e depois Accept new permissions.

Depois da aprovação, o próximo evento do pull request, como um novo push, cria ou atualiza o preview.

Herança e comportamento do Preview

Todo Preview herda, dentro da plataforma, as variáveis configuradas pelo usuário no projeto principal em cada criação ou atualização. Os valores nunca são expostos pela API, Console ou Action.

Os valores das variáveis nunca passam pela Action, pelos outputs, pelo Job Summary ou pelos logs. Variáveis gerenciadas pela Zenifra são regeneradas para o preview, em vez de serem tratadas como variáveis do projeto principal.

Atenção: variáveis herdadas podem apontar para os mesmos bancos de dados, filas, buckets ou outros serviços usados pelo projeto principal. Revise essas variáveis antes de usar o preview quando o compartilhamento não for desejado.

O preview herda do projeto principal a porta, a exposição e as regras de acesso necessárias para executar a aplicação. O storage é novo e começa vazio para o preview; dados do projeto principal não são herdados.

Estas configurações não são herdadas nem criadas atualmente:

• dados de bancos, filas, buckets e outros serviços
• domínios personalizados
• comandos customizados de inicialização da imagem

Limites de ambientes de preview por organização

Os ambientes ativos são limitados em dois níveis: organização e projeto principal. O limite efetivo de um preview é sempre o menor entre os dois.

• Por organização: uma organização pode ter, no máximo, 10 ambientes de preview ativos simultaneamente.
• Por projeto: um projeto principal pode ter, no máximo, 2 ambientes de preview ativos simultaneamente.
• TTL máximo: um preview pode expirar em até 168 horas (7 dias) após a última atualização.

Os limites são contados enquanto o preview existe, independentemente do plano: cada preview ativo consome uma posição nos dois limites. Criar um preview além do limite efetivo faz a operação terminar como failed, com uma mensagem pública informando que o limite da organização ou do projeto foi atingido; a Action encerra o job com falha.

O opt-in do projeto, os limites configurados no console e o entitlement da organização são sempre aplicados antes de qualquer criação, atualização ou remoção. A API pública não altera o limite da organização: as configurações do projeto podem ser ajustadas no console, mas o limite da organização é definido pela Zenifra.

Como aumentar o limite da organização

Se a sua organização precisa de mais ambientes de preview simultâneos, envie um email para [email protected] informando:

1. o nome e o e-mail de acesso da organização;
2. o limite atual em uso (quantos previews ativos a organização costuma manter);
3. o limite desejado e o motivo (por exemplo: múltiplas frentes de desenvolvimento em pull requests paralelos).

A equipe Zenifra avalia a solicitação, ajusta o limite da organização e confirma por email. Depois da aprovação, os novos limites passam a valer imediatamente para os próximos upserts, sem necessidade de alterar os workflows.

Inputs da GitHub Action

Esta seção descreve o fluxo explícito da Action. Ela é independente dos Previews nativos para pull requests e continua válida para projetos com imagem pronta, inclusive projetos que não usam origem GitHub.

Use os nomes exatamente como aparecem abaixo. Os inputs existentes continuam funcionando quando PREVIEW está ausente ou false; nesse caso, a Action atualiza apenas o projeto principal.

Todo Preview herda os ENVs do usuário do projeto principal em cada upsert, sem expor seus valores.

O Ambiente de Preview sempre herda o plano do projeto principal. Se o projeto usa basic, o preview usa basic; não existe PREVIEW_PLAN nem preço separado de preview.

A Action valida booleanos, duração, ação e contexto antes de fazer a chamada. IMAGE é condicional: não é necessário para uma remoção. Valores inválidos, plano não permitido e TTL fora do limite encerram o job com uma mensagem pública e acionável.

Workflow recomendado para pull requests

Este workflow usa uma única chave derivada do número do pull request. Atualizações do mesmo pull request reaproveitam o preview, e o evento closed aciona a remoção por meio de PREVIEW_ACTION=auto.

name: Zenifra preview

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]

permissions:
  contents: read

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Create or remove preview
        id: zenifra-preview
        uses: zenifra/[email protected]
        with:
          PROJECT_ID: ${{ vars.ZENIFRA_PROJECT_ID }}
          API_KEY: ${{ secrets.ZENIFRA_API_KEY }}
          IMAGE: ${{ vars.ZENIFRA_PREVIEW_IMAGE }}
          PREVIEW: true
          PREVIEW_ACTION: auto
          PREVIEW_TTL: 24h
          WAIT_TIMEOUT: 10m

No evento closed, a Action não precisa da imagem para remover o ambiente. Os outputs de um upsert ficam disponíveis somente depois que a operação chega a available; se a operação falhar, o job termina com erro.

Workflow manual com PREVIEW_KEY

Use workflow_dispatch para testar uma branch, uma versão específica ou um fluxo que não seja executado por pull request. Neste caso, a chave é obrigatória e deve ser escolhida por você.

name: Zenifra manual preview

on:
  workflow_dispatch:
    inputs:
      preview_key:
        description: Chave estável do Ambiente de Preview
        required: true
        type: string
      action:
        description: Operação desejada
        required: true
        default: upsert
        type: choice
        options:
          - upsert
          - delete

permissions:
  contents: read

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Run preview operation
        id: zenifra-preview
        uses: zenifra/[email protected]
        with:
          PROJECT_ID: ${{ vars.ZENIFRA_PROJECT_ID }}
          API_KEY: ${{ secrets.ZENIFRA_API_KEY }}
          IMAGE: ${{ vars.ZENIFRA_PREVIEW_IMAGE }}
          PREVIEW: true
          PREVIEW_KEY: ${{ inputs.preview_key }}
          PREVIEW_ACTION: ${{ inputs.action }}
          PREVIEW_TTL: 24h
          WAIT_TIMEOUT: 10m

Ao selecionar delete, IMAGE pode ser omitida. Não reutilize a mesma chave para mudanças que precisem existir ao mesmo tempo: a chave representa um único ambiente lógico.

Outputs, polling e status

A Action acompanha a operação com polling limitado. Ela aguarda available para um upsert e deleted para uma remoção. Estados transitórios incluem accepted, reserving, provisioning, updating e deleting; failed encerra o job com falha.

Quando o estado esperado é alcançado, a Action fornece:

O Job Summary contém o resultado público da operação, mas nunca contém API Keys, variáveis de ambiente ou credenciais. Timeout de espera e estado terminal incompatível fazem o job falhar; repetir a mesma operação com a mesma chave é seguro.

Erros públicos e solução

As mensagens são voltadas ao produto e não revelam detalhes operacionais. A API retorna um campo code que ajuda a corrigir o workflow; a Action mostra uma mensagem pública equivalente no job:

• preview_disabled: habilite Ambientes de Preview no projeto principal.
• preview_ttl_invalid ou preview_ttl_exceeds_limit: use um TTL entre 1h e 168h que respeite a expiração máxima configurada no projeto.
• PREVIEW_OPERATION_CONFLICT: outra operação já está em andamento para a chave; aguarde ou consulte a operação existente, sem criar uma nova chave para contornar o estado.
• PARENT_CONFIGURATION_UNAVAILABLE: confira a configuração do projeto principal antes de tentar novamente.
• PARENT_IMAGE_AUTHENTICATION_UNAVAILABLE: revise as credenciais de imagem privada do projeto principal.
• Operação failed por limite atingido: aguarde a remoção de um ambiente ou solicite um limite maior.
• Chave fora do formato permitido: a Action rejeita a execução antes de chamar a API.
• Timed out waiting for the preview operation to finish.: aumente WAIT_TIMEOUT até 15m ou consulte a operação novamente.

Nenhum erro público inclui nomes de recursos, topologia, credenciais, variáveis, URLs privadas ou detalhes do processo de limpeza.

Próximos passos

• Implantação via GitHub
• Referência de API dos Ambientes de Preview
• Automático por branch
• Portas e health checks