Implementações de pré-visualização dão a cada pull request o seu próprio URL em funcionamento, construído a partir do código desse ramo, para que os revisores possam percorrer a alteração real em vez de ler um diff e adivinhar. Cada pré-visualização atualiza quando faz push de um novo commit e é limpa automaticamente quando o pull request é fechado.
Onde Vivem as Implementações de Pré-visualização
Abra Websites, clique no site, abra o grupo Environment no menu esquerdo do site e escolha Pré-visualização. A página tem o título Implementações de pré-visualização.
As pré-visualizações são separadas do staging. O staging é uma cópia duradoura do site que atualiza deliberadamente; uma pré-visualização é um ambiente de curta duração criado por pull request e descartado depois. Muitas equipas usam ambos. Consulte Ambientes de Staging para a outra metade.
Configure a Implementação Git Primeiro
As pré-visualizações não são uma funcionalidade autónoma. Reutilizam a chave de implementação e o comando de construção do site de produção, pelo que o site precisa de uma configuração de Implementação Git funcional antes de as pré-visualizações poderem ser ativadas.
Se a Implementação Git não estiver configurada, a página indica Configure a implementação Git primeiro e oferece um botão Ir para implementação Git em vez do formulário de ativação. Siga Implementar um Site a Partir do Git e depois volte.
Se a Implementação Git estiver ligada mas não tiver comando de construção, a página de Pré-visualização mostra um aviso. As pré-visualizações assumirão que o repositório já está construído, com ficheiros estáticos na raiz. Isso é correto para um site HTML simples e errado para qualquer coisa que necessite de compilação, por isso defina um comando de construção na página de Implementação Git se o seu projeto precisar de um.
Ativar Pré-visualizações
- No cartão Ativar implementações de pré-visualização, digite o repositório no formato
owner/repo. Não um URL, nem um endereço SSH: apenas os dois segmentos, por exemploacme/marketing-site. - Clique em Ativar.
Qualquer coisa que não corresponda a owner/name é rejeitada com O repositório deve estar no formato proprietário/nome.
Imediatamente após ativar, o KPanel mostra o segredo de assinatura do webhook num cartão intitulado Copie o seu segredo webhook agora, com um aviso de que não o voltará a ver.
Copie o segredo antes de sair da página. É gerado uma única vez e não pode ser recuperado depois. Se o perder, a solução é regenerá-lo, o que invalida o anterior e implica atualizar o webhook do seu repositório de qualquer forma.
Adicionar o Webhook ao Seu Repositório
O cartão configurado mostra um URL do webhook para colar nas definições do seu repositório, em Webhooks. Configure-o com:
- URL de Payload: o URL do webhook apresentado na página.
- Segredo: o valor que acabou de copiar.
- Tipo de conteúdo: JSON.
- Eventos: eventos de pull request, mais pushes, para que novos commits num pull request aberto reconstruam a pré-visualização.
Assim que isso estiver configurado, abrir um pull request constrói uma pré-visualização em poucos minutos. Uma tarefa em segundo plano verifica se há novo trabalho de pré-visualização a cada minuto, pelo que não é necessário clicar em nada no KPanel.
URLs de Pré-visualização
Cada pré-visualização recebe o seu próprio nome de anfitrião no formato pr-<pull-request-number>-<site-id>.kapsulecloud.app, coberto por um certificado wildcard, pelo que é servido via HTTPS sem qualquer passo de certificado da sua parte.
A forma fiável de abrir uma é o botão Open na linha da pré-visualização em Previews recentes, que contém o URL exato que foi provisionado para essa construção. Cole esse link no pull request para que os revisores nem precisem de encontrar o KPanel.
Ler a Lista de Previews Recentes
A secção Previews recentes lista as pré-visualizações mais recentes, começando pela mais recente. Cada linha mostra o número e o título do pull request, o ramo, o commit e um estado:
| Estado | Significado |
|---|---|
| BUILDING | A clonar e a construir agora |
| LIVE | A servir no seu URL de pré-visualização |
| FAILED | A construção falhou; expanda o registo para ver porquê |
| DESTROYED | Limpa, normalmente porque o pull request foi fechado |
Clique em Alternar registo de construção numa linha para expandir a sua saída de construção em linha. Esse registo é o primeiro sítio a verificar quando uma pré-visualização falha, e é a mesma saída que a sua construção produziria localmente.
Se a lista estiver vazia, a página indica isso mesmo: abra um pull request no repositório e uma pré-visualização será construída em poucos minutos.
Rodar o Segredo do Webhook
Clique em Regenerar segredo no cartão configurado. O KPanel pede confirmação e é explícito quanto ao facto de o segredo atual deixar de funcionar imediatamente, sendo necessário atualizá-lo depois nas definições de webhook do seu repositório.
O novo segredo é mostrado uma única vez, no mesmo cartão temporário de antes. Copie-o e, em seguida, atualize o webhook no seu repositório. Entre esses dois momentos, as entregas de webhook recebidas são rejeitadas, por isso faça os dois passos seguidos.
Regenere o segredo quando alguém com acesso de administrador ao repositório sair da equipa, ou se o segredo alguma vez tiver sido colado num local onde não deveria estar, como um canal de chat partilhado ou um ticket.
Desativar Pré-visualizações
Clique em Desativar. A configuração é desligada e o segredo armazenado é apagado. As pré-visualizações existentes deixam de ser reconstruídas.
Organize também eliminando o webhook no seu repositório. Começará a falhar em vez de fazer algo prejudicial, mas um webhook que devolve erros para sempre é ruído no registo de entregas do seu repositório.
Custos e Manutenção
As pré-visualizações constroem e servem código real, pelo que usam os mesmos recursos que qualquer outra implementação no site. Dois hábitos mantêm isso sob controlo:
- Feche os pull requests em que já não está a trabalhar. Um pull request fechado tem a sua pré-visualização limpa automaticamente.
- Não aponte as pré-visualizações para credenciais de produção. Dê-lhes chaves de teste através do ambiente preview no separador Secrets, que existe precisamente para que a configuração de pré-visualização e de produção não possam ser confundidas.
Um URL de pré-visualização não é privado. É um nome de anfitrião real, acessível publicamente, com um certificado válido, e qualquer pessoa que tenha o link pode abri-lo. Não utilize uma pré-visualização para rever nada que contenha dados reais de clientes, e não semeie ambientes de pré-visualização a partir de um dump de base de dados de produção.
Resolução de Problemas
Nada é construído quando um pull request é aberto. Verifique as entregas recentes do webhook no seu repositório. Um 401 ou 403 significa que o segredo não corresponde, por isso regenere-o e atualize ambos os lados. Nenhuma entrega significa que o webhook não está subscrito a eventos de pull request.
A pré-visualização é construída mas mostra uma listagem de diretório ou um 404. O diretório de saída na página de Implementação Git não corresponde ao local onde a sua construção realmente escreve. As pré-visualizações herdam essa definição da produção.
A construção falha apenas na pré-visualização. A causa mais comum é uma dependência ou uma variável de ambiente que existe em produção mas que nunca foi adicionada ao ambiente de pré-visualização. Verifique o separador preview na página Secrets.
Um URL de pré-visualização deixa de funcionar. Observe o estado na sua linha. DESTROYED significa que o pull request foi fechado e o ambiente foi recuperado, o que é o comportamento pretendido.
Próximos Passos
- Implementar um Site a Partir do Git, a configuração pré-requisito.
- Armazenar Segredos de Aplicação para um Site para credenciais por ambiente.
- Ambientes de Staging para uma cópia persistente de pré-produção.