Ambientes de Preview

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

A GitHub Action da Zenifra cria ou atualiza o preview a partir de uma imagem pronta, aguarda a disponibilidade e publica os outputs necessários para o workflow. Quando o pull request é fechado, a mesma Action pode remover o preview automaticamente.

Antes de começar

1. Tenha um projeto HTTP na Zenifra.
2. No console, abra a aba Previews do projeto principal e habilite Ambientes de Preview.
3. Defina o plano padrão, os planos permitidos, o TTL padrão e máximo e o limite de ambientes ativos.
4. Guarde a API Key do projeto principal em um secret do GitHub. Nunca coloque a chave diretamente no arquivo YAML, no Job Summary ou em logs.
5. Tenha uma imagem pronta para publicar e disponibilize sua referência 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 apenas 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.

Cada upsert renova a expiração. 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.

Herança e isolamento

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. Habilite a herança somente quando esse compartilhamento 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 do preview é sempre próprio, vazio e isolado: dados do projeto principal nunca são clonados nem compartilhados.

Estas configurações não são herdadas ou criadas no MVP:

• 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 falha com preview_organization_limit_reached ou preview_project_limit_reached; a Action encerra o job com uma mensagem pública e acionável.

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 Action

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/action-zenifra-deploy@v1
        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 ou falha de forma terminal.

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/action-zenifra-deploy@v1
        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 terminal é 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. Os códigos estáveis ajudam a corrigir o workflow:

• preview_not_enabled: habilite Ambientes de Preview no projeto principal.
• invalid_preview_key: use uma chave dentro do formato permitido.
• preview_ttl_out_of_range: use um TTL entre 1h e 168h.
• preview_limit_reached: aguarde a remoção de um ambiente ou ajuste o limite permitido.
• parent_configuration_unavailable: confira a configuração do projeto principal antes de tentar novamente.
• preview_operation_in_progress: consulte a operação existente; não crie uma nova chave para contornar o estado.
• preview_unavailable: revise a imagem e a configuração pública da aplicação.
• preview_wait_timeout: aumente WAIT_TIMEOUT dentro do limite permitido 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
• Auto-deploy
• Portas e health checks