Docs/ Implantação/ Ambientes de Preview

Ambientes de Preview

Cada pull request recebe sua própria implantação ativa com uma URL única. Revise alterações em um ambiente real antes de mergear, depois limpe automaticamente quando o PR for fechado.

O que são Ambientes de Preview

Ambientes de preview são implantações temporárias e totalmente funcionais criadas automaticamente para cada pull request. Eles permitem testar alterações em um ambiente isolado que espelha a produção, sem afetar sua aplicação ativa.

Quando um membro da equipe abre um PR, o sh0 constrói a branch, implanta em uma URL única e posta um comentário no PR com o link do preview. Quando o PR é mergeado ou fechado, o ambiente de preview é automaticamente destruído.

GitHub pull request with an sh0 bot comment showing the preview URL and deploy status

Habilitando Previews

Ambientes de preview são habilitados por aplicação. Navegue até Configurações do App → Git → Ambientes de Preview e ative o recurso. Você precisará de um provedor Git conectado (GitHub, GitLab ou Bitbucket) com acesso a webhooks.

Preview environment toggle in app settings

Uma vez habilitado, o sh0 escuta eventos de pull request do seu provedor Git:

  • PR aberto: Construir e implantar a branch
  • PR atualizado (novo push): Reconstruir e reimplantar
  • PR mergeado ou fechado: Destruir o ambiente de preview
Note
Ambientes de preview requerem que seu provedor Git esteja conectado via OAuth para que o sh0 possa receber eventos de PR e postar atualizações de status. Configurações manuais de webhook não suportam ambientes de preview.

Implantações Automáticas de PR

Quando um pull request é aberto, o sh0 automaticamente:

  1. Clona a branch do PR
  2. Constrói uma imagem Docker usando o mesmo pipeline de build da produção
  3. Inicia um novo contêiner com o código do PR
  4. Atribui uma URL de preview única
  5. Posta um comentário no PR com o link do preview e status do build
  6. Atualiza o status check do PR (checkmark verde ou X vermelho)
Deployment in progress for a pull request with real-time build log

Quando novos commits são enviados para a branch do PR, o sh0 automaticamente reconstrói e reimplanta o preview. A URL permanece a mesma, então os revisores sempre veem a versão mais recente.

Tip
Você pode configurar o sh0 para construir previews apenas para PRs direcionados a branches específicas (ex.: apenas PRs para main). Isso evita builds desnecessários para PRs entre feature branches.

URLs de Preview

Cada ambiente de preview recebe uma URL única baseada no nome da branch e no nome da aplicação:

Preview URL format
https://{branch-name}.{app-name}.your-domain.com

Por exemplo, se sua aplicação se chama my-api e a branch do PR é feature/new-auth, a URL de preview seria:

Example preview URL
https://feature-new-auth.my-api.sh0.app

Nomes de branches são sanitizados para uso em URLs: barras são substituídas por hífens e caracteres especiais são removidos. Certificados SSL são provisionados automaticamente para cada URL de preview via Caddy.

Note
Se você usa um registro DNS wildcard para seu domínio (ex.: *.my-api.your-domain.com), URLs de preview funcionam imediatamente. Caso contrário, o sh0 provisiona registros DNS individuais para cada preview.

Configurações de Ambientes de Preview

Você pode personalizar como os ambientes de preview se comportam:

  • Filtro de branch base: Construir previews apenas para PRs direcionados a branches específicas
  • Sobrescritas de variáveis de ambiente: Definir variáveis específicas de preview (ex.: NODE_ENV=staging)
  • Limites de recursos: Limitar CPU e memória para contêineres de preview para economizar recursos
  • TTL (tempo de vida): Destruir previews automaticamente após uma duração especificada, mesmo se o PR ainda estiver aberto
  • Máximo de previews simultâneos: Limitar o número de ambientes de preview ativos para controlar o uso de recursos
Preview environment settings panel with filters, resource limits, and TTL configuration

Limpeza Automática

Quando um pull request é mergeado ou fechado, o sh0 limpa automaticamente o ambiente de preview:

  1. O contêiner de preview é parado e removido
  2. A imagem Docker é excluída para liberar espaço em disco
  3. A rota do Caddy é removida
  4. O certificado SSL é limpo
  5. Quaisquer volumes específicos do preview são excluídos (a menos que configurados para persistir)

Você também pode destruir manualmente um ambiente de preview pelo painel sem fechar o PR. Isso é útil se um preview está consumindo recursos e não é mais necessário para revisão.

Warning
Dados de ambientes de preview (bancos de dados, uploads de arquivos) são efêmeros por padrão. Se seus ambientes de preview precisam de dados iniciais, use um hook de pré-deploy para popular o banco de dados em cada implantação.

Isolamento de Banco de Dados

Ambientes de preview podem ser configurados para usar bancos de dados isolados. O sh0 suporta duas estratégias:

  • Banco de dados compartilhado: Ambientes de preview se conectam ao mesmo banco de dados do staging ou produção (somente leitura recomendado). Configure via sobrescritas de variáveis de ambiente.
  • Banco de dados isolado: O sh0 cria um contêiner de banco de dados dedicado para cada preview. O banco de dados é populado a partir de um snapshot ou script de migração e destruído junto com o preview.
Preview environment with isolated database
preview:
  enabled: true
  database_isolation: true
  seed_command: "pg_restore --dbname=$DATABASE_URL /seeds/staging.dump"
  max_concurrent: 5
  ttl: 72h
Tip
Para a melhor experiência de revisão, combine ambientes de preview com bancos de dados isolados e dados iniciais do seu ambiente de staging. Isso oferece aos revisores um preview realista de como as mudanças se comportarão em produção.
Previous
Deploy Hooks
Next
Blue-Green & Rollbacks