# Implantações de Pré-visualização Para Pull Requests

Source: https://support.kapsulehost.com/pt-pt/site-preview

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](https://support.kapsulehost.com/pt-pt/staging-environments) para a outra metade.

![A página de implementações de pré-visualização para um site no KPanel](https://support.kapsulehost.com/help/screenshots/site-preview.0fb977c9.webp)

## 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](https://support.kapsulehost.com/pt-pt/site-git-deploy) e depois volte.

> **Note:** 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

1. 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 exemplo `acme/marketing-site`.
2. 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.

> **Important:** 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](https://support.kapsulehost.com/pt-pt/site-secrets), que existe precisamente para que a configuração de pré-visualização e de produção não possam ser confundidas.

> **Warning:** 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](https://support.kapsulehost.com/pt-pt/site-git-deploy), a configuração pré-requisito.
- [Armazenar Segredos de Aplicação para um Site](https://support.kapsulehost.com/pt-pt/site-secrets) para credenciais por ambiente.
- [Ambientes de Staging](https://support.kapsulehost.com/pt-pt/staging-environments) para uma cópia persistente de pré-produção.