Sites
Pré-visualizações de Implementações para Pedidos de Integração
Preview deploys give every pull request its own live URL, built from that branch's code, so reviewers can click through the actual change instead of reading a diff and guessing. Each preview updates…
Implementações de Pré-visualização Para Pull Requests
As implementações de pré-visualização dão a cada pull request seu próprio URL ao vivo, compilado a partir do código dessa branch, para que os revisores possam clicar na mudança real em vez de ler um diff e adivinhar. Cada pré-visualização é atualizada quando você faz push de um novo commit e é limpada automaticamente quando o pull request é fechado.
Onde as Implementações de Pré-visualização Vivem
Abra Websites, clique no site, abra o menu Environments na barra de abas do site e escolha Preview. A página tem o título Preview deploys.
As pré-visualizações são separadas do staging. O staging é uma cópia única de longa duração do site para o qual você faz push deliberadamente; uma pré-visualização é um ambiente de curta duração criado por pull request e descartado depois. Muitas equipas usam ambos. Consulte Staging Environments para a outra metade.
Configure Git Deploy Primeiro
As pré-visualizações não são uma funcionalidade autónoma. Reutilizam a chave de implementação e o comando de compilação do site de produção, portanto, o site precisa de uma configuração Git Deploy funcional antes que as pré-visualizações possam ser ativadas.
Se Git Deploy não estiver configurado, a página diz Set up Git deploy first e oferece um botão Go to Git deploy em vez do formulário de ativação. Trabalhe em Deploying a Site From Git e depois volte.
Se Git Deploy estiver conectado mas não tiver comando de compilação, a página Preview mostra um aviso. As pré-visualizações assumirão que o repositório já está compilado, com arquivos estáticos na raiz. Isto é correto para um site HTML simples e errado para qualquer coisa que seja compilada, portanto, defina um comando de compilação na página Git Deploy se o seu projeto precisar.
Ativar Pré-visualizações
- No cartão Enable preview deploys, digite o repositório no formato
owner/repo. Não um URL, não um endereço SSH: apenas os dois segmentos, por exemploacme/marketing-site. - Clique em Enable.
Qualquer coisa que não corresponda a owner/name é rejeitada com Repo must be in owner/name format.
Imediatamente após ativar, KPanel mostra o segredo de assinatura do webhook num cartão com o título Copy your webhook secret now, com um aviso de que não o verá novamente.
Copie o segredo antes de sair da página. É gerado uma vez e não é recuperável depois. Se o perder, a solução é regenerá-lo, o que invalida o antigo e significa atualizar o webhook do seu repositório de qualquer forma.
Adicionar o Webhook ao Seu Repositório
O cartão configurado mostra um Webhook URL para colar nas definições do seu repositório, em Webhooks. Configure-o com:
- Payload URL: o URL do webhook mostrado na página.
- Secret: o valor que acabou de copiar.
- Content type: JSON.
- Events: eventos de pull request, mais pushes, para que novos commits num pull request aberto reconstruam a pré-visualização.
Quando isso estiver em vigor, abrir um pull request cria uma pré-visualização dentro de alguns minutos. Um trabalho em segundo plano verifica se há novo trabalho de pré-visualização a cada minuto, portanto, não há necessidade de pressionar nada em KPanel.
URLs de Pré-visualização
Cada pré-visualização obtém seu próprio nome de host do formulário pr-<pull-request-number>-<site-id>.kapsulecloud.app, coberto por um certificado wildcard para que seja servido por HTTPS sem nenhuma etapa de certificado da sua parte.
A forma confiável de abrir um é o botão Open na linha da pré-visualização em Recent previews, que contém o URL exato que foi provisionado para essa compilação. Cole esse link no pull request para que os revisores não precisem encontrar KPanel.
Ler a Lista de Pré-visualizações Recentes
A secção Recent previews lista as pré-visualizações mais recentes, a mais nova primeiro. Cada linha mostra o número e título do pull request, a branch, o commit e um estado:
| Estado | Significado |
|---|---|
| BUILDING | A clonar e compilar agora |
| LIVE | A servir no seu URL de pré-visualização |
| FAILED | A compilação teve erro; expanda o registo para ver o motivo |
| DESTROYED | Limpo, geralmente porque o pull request foi fechado |
Clique em Toggle build log numa linha para expandir a sua saída de compilação inline. Esse registo é o primeiro lugar a procurar quando uma pré-visualização falha, e é a mesma saída que a sua compilação produziria localmente.
Se a lista estiver vazia, a página o diz: abra um pull request no repositório e uma pré-visualização será compilada dentro de minutos.
Rodar o Segredo do Webhook
Clique em Regenerate secret no cartão configurado. KPanel pede-lhe para confirmar e é explícito que o segredo atual deixa de funcionar imediatamente e precisará de atualizá-lo nas definições do webhook do seu repositório depois.
O novo segredo é mostrado uma vez, no mesmo cartão de uso único de antes. Copie-o e depois atualize o webhook no seu repositório. Entre esses dois momentos, as entregas de webhook recebidas são rejeitadas, portanto, faça os dois passos de forma consecutiva.
Regenere o segredo quando alguém com acesso de administrador ao repositório sair, ou se o segredo tiver sido colado alguma vez num local onde não deveria ter sido, como um canal de chat partilhado ou um ticket.
Desativar Pré-visualizações
Clique em Disable. A configuração é desligada e o segredo armazenado é limpo. As pré-visualizações existentes deixam de ser reconstruídas.
Organize-se eliminando também o webhook no seu repositório. Começará a falhar em vez de fazer algo prejudicial, mas um webhook que retorna erros para sempre é ruído no registo de entrega do seu repositório.
Custos e Limpeza
As pré-visualizações compilam e servem código real, portanto, usam os mesmos recursos que qualquer outra implementação no site. Dois hábitos mantêm isso sob controlo:
- Feche pull requests nos quais não está mais a trabalhar. Um pull request fechado tem a sua pré-visualização limpa automaticamente.
- Não aponte pré-visualizações para credenciais de produção. Dê-lhes chaves de teste através da aba Secrets do ambiente preview, que existe precisamente para que a configuração de pré-visualização e produção não possam ser confundidas.
Um URL de pré-visualização não é privado. É um nome de host real, acessível publicamente, com um certificado válido, e qualquer pessoa que tenha o link pode abri-lo. Não use uma pré-visualização para rever qualquer coisa que contenha dados de cliente reais e não semeie ambientes de pré-visualização a partir de um despejo de base de dados de produção.
Resolução de Problemas
Nada é compilado 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, portanto, regenere-o e atualize ambas as extremidades. Nenhuma entrega em absoluto significa que o webhook não está subscrito a eventos de pull request.
A pré-visualização compila mas mostra uma listagem de diretório ou um 404. O diretório de saída na página Git Deploy não corresponde ao local onde a sua compilação realmente escreve. As pré-visualizações herdam essa definição de produção.
A compilaçã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 nunca foi adicionada ao ambiente de pré-visualização. Verifique a aba preview na página Secrets.
Um URL de pré-visualização deixa de funcionar. Procure no estado da sua linha. DESTROYED significa que o pull request foi fechado e o ambiente foi recuperado, que é o comportamento pretendido.
Para Onde Ir A Seguir
- Deploying a Site From Git, a configuração de pré-requisito.
- Storing App Secrets For a Site para credenciais por ambiente.
- Staging Environments para uma cópia pré-produção persistente.