# Implementar um Site a Partir do Git

Source: https://support.kapsulehost.com/pt-pt/site-git-deploy

O Git Deploy liga um repositório a um site, de forma que cada push para o ramo escolhido clona o código, executa a compilação e publica o resultado. Este guia aborda a ligação inicial, os dois passos do lado do repositório que concluem a configuração, a leitura do histórico de implementações e a deteção do buildpack que determina como uma aplicação Node.js é compilada.

## Onde Se Encontra o Git Deploy

Abra **Websites**, clique no site, abra o grupo **Environment** no menu esquerdo do site e escolha **Implementação Git**. Existem duas páginas relacionadas por perto:

- **Implementações**, o histórico completo de implementações deste site, no mesmo grupo **Environment**.
- **Buildpack**, a estratégia de compilação detetada, em sites Node.js, no grupo **Aplicações**.

A página Git Deploy descreve-se de forma clara: ligue um repositório e cada push para o ramo configurado despoleta uma compilação e implementação.

![A página Git Deploy de um site no KPanel, onde um repositório está ligado](https://support.kapsulehost.com/help/screenshots/site-git-deploy.4716f1a9.webp)

## Ligar um Repositório

1. Escolha o seu **Provider**: GitHub, GitLab ou Bitbucket.
2. Introduza o **URL do Repositório**. A forma SSH é a que pretende, por exemplo `git@github.com:user/repo.git`.
3. Defina o **Branch** a partir do qual implementar. O campo começa em `main`.
4. Opcionalmente, defina um **Comando de compilação**, por exemplo `npm run build`.
5. Opcionalmente, defina um **Diretório de saída**, por exemplo `dist`, `public`, ou `.` para um repositório que já esteja compilado.
6. Clique em **Conectar repositório**.

Deixe o comando de compilação e o diretório de saída vazios se o seu repositório já estiver pronto a implementar tal como está, o que é o caso comum de um site simples em PHP ou estático.

### Scripts Avançados

Ao expandir **Avançado** surgem dois campos adicionais:

- **Script de pré-implantação**, que é executado antes da compilação.
- **Script de pós-implantação**, que é executado depois da implementação.

Use o gancho de pós-implantação para as coisas que têm de acontecer assim que o novo código estiver pronto: limpar a cache de uma aplicação, executar uma migração de base de dados, reiniciar um worker.

### Implementação Automática Ao Fazer Push

O interruptor na parte inferior do cartão controla se os pushes despoletam ou não implementações. Quando está ativado, cada push para o ramo configurado despoleta uma implementação. Quando está desativado, as implementações só são executadas quando as despoleta manualmente com **Implementar agora**.

> **Tip:** Desative a implementação automática durante um code freeze ou um incidente, em vez de desligar o repositório. Desligar descarta a chave de implementação e o segredo do webhook, pelo que terá de refazer ambos os passos do lado do repositório posteriormente.

## Concluir a Configuração No Seu Repositório

Ligar o repositório no KPanel é apenas o primeiro de três passos. Até que uma implementação tenha sido executada, a página mostra um aviso com o texto **Completar configuração: 2 passos restantes** com tudo o que precisa.

### Passo 2: Adicionar a Chave de Implementação

A KapsuleHost precisa de acesso de leitura para clonar o seu repositório. O aviso mostra uma chave pública com um botão **Copiar chave**.

Cole-a nas chaves de implementação do seu repositório. Para o GitHub, o aviso oferece um atalho **Adicionar ao GitHub** diretamente para a página de definições correta. O acesso de leitura é suficiente; não conceda acesso de escrita.

### Passo 3: Adicionar o Webhook

O webhook é o que informa a KapsuleHost de que ocorreu um push. O aviso fornece três valores:

| Campo | Valor |
|---|---|
| URL de Payload | Um URL terminado em `/api/git-deploy/webhook/` mais o ID deste site |
| Segredo | Um segredo de assinatura gerado, oculto até clicar no ícone do olho |
| Tipo de Conteúdo | `application/json` |

Copie cada um para as definições de webhook do seu repositório. Para o GitHub existe um atalho **Adicionar webhook ao GitHub**. Defina o tipo de conteúdo como JSON, não a predefinição com codificação de formulário, caso contrário o payload não será processado.

> **Warning:** Trate o segredo do webhook como uma palavra-passe. Quem o tiver, mais o URL de payload, pode despoletar uma implementação do seu site. Ambos os valores só são mostrados a pessoas que já podem administrar o site, e o segredo permanece oculto atrás do ícone do olho até ser solicitado.

## Implementar Manualmente

Clique em **Implementar agora** na página Git Deploy para compilar e implementar o head atual do ramo configurado sem fazer push de um commit. Isto funciona quer a implementação automática esteja ativada ou não, o que faz dela a ferramenta certa durante um freeze: os pushes são ignorados, mas ainda assim é possível lançar a correção.

## Ler o Histórico de Implementações

Abra **Environment**, depois **Implementações**. A página tem o título **Histórico de implementações** e lista todas as implementações despoletadas por webhook ou manualmente, das mais recentes para as mais antigas.

Cada linha apresenta:

- Um ícone de estado e o SHA abreviado do commit, com o ramo apresentado como uma etiqueta.
- A mensagem do commit, ou **Implementação manual** se não existir mensagem de commit para mostrar.
- O autor, há quanto tempo foi executada, quanto tempo demorou e o que a despoletou.
- Uma etiqueta de estado.

Os estados são **pending**, **building**, **deploying**, **success** e **failed**. Enquanto algo estiver em curso, a página atualiza-se automaticamente a cada cinco segundos e mostra uma nota **Refreshing automatically** por baixo da tabela, pelo que pode deixá-la aberta e observar a implementação a concluir-se.

### Quando Uma Implementação Falha

Uma linha falhada tem um botão **Error** à direita. Clique nele para expandir a saída de erro capturada diretamente na página, sem sair dela. Essa saída é o próprio texto de erro da compilação, pelo que normalmente indica o ficheiro ou o comando que falhou.

Siga esta ordem: leia o erro, reproduza o mesmo comando de compilação localmente, corrija, faça push. Se a compilação funciona localmente mas não aqui, a diferença é quase sempre do ambiente, uma dependência em falta que está instalada globalmente na sua máquina, ou um ficheiro que está na sua pasta de trabalho mas não foi submetido.

## Deteção de Buildpack

Em sites Node.js, a página **Buildpack** no grupo **Aplicações** mostra como a KapsuleHost decidiu compilar a sua aplicação. A deteção percorre os ficheiros na raiz do seu repositório, e a primeira correspondência prevalece:

| Detetado | Gatilho |
|---|---|
| Buildpack personalizado | `kapsule.config.yaml` ou `kapsule.config.yml` na raiz |
| Buildpack Dockerfile | `Dockerfile` na raiz |
| Node.js | `package.json` com um script `start`, `build` ou `dev` |
| Python | `requirements.txt` ou `pyproject.toml` |
| PHP | `composer.json` |
| Estático | `index.html` na raiz |

Se nada corresponder, a página indica-o e lista os gatilhos suportados. Adicione um `Dockerfile` ou um `kapsule.config.yaml` para assumir o controlo explícito da compilação.

### Executar Uma Compilação

Clique em **Executar compilação** para a colocar em fila. A página consulta o estado a cada três segundos enquanto uma execução está em curso, e a tabela **Compilações recentes** mostra as últimas execuções com a respetiva hora de início, tipo, estado, duração e referência de imagem resultante. Clique numa linha para ver o final do seu registo.

Apenas uma compilação pode estar em curso de cada vez. Despoletar uma segunda enquanto outra está em fila ou em execução é recusado com **Uma compilação já está em progresso**, o que é deliberado: duas compilações a escrever o mesmo resultado ao mesmo tempo é como se obtém um site meio implementado.

## Desligar

Clique em **Disconnect** e confirme. A confirmação é explícita quanto ao impacto: a configuração de Git Deploy e a chave de implementação são removidas, e os ficheiros do seu site não são afetados. O site continua a servir o que foi implementado pela última vez.

Depois, organize tudo apagando a chave de implementação e o webhook nas definições do seu repositório. Simplesmente deixarão de funcionar, mas deixar entradas inativas por aí torna a próxima auditoria mais difícil.

## Resolução de Problemas

**Os pushes não despoletam nada.** Verifique primeiro o interruptor de implementação automática, depois o webhook no seu repositório. A maioria dos fornecedores mostra as entregas recentes e os respetivos códigos de resposta, o que indica de imediato se o pedido chegou sequer a sair do seu repositório.

**A clonagem falha.** A chave de implementação está em falta, foi colada com uma quebra de linha, ou foi adicionada ao repositório errado. Copie-a novamente com o botão **Copiar chave** em vez de selecionar o texto manualmente.

**A implementação é bem-sucedida mas o site não muda.** O diretório de saída está provavelmente errado. Se a sua compilação escreve em `dist` e o diretório de saída está vazio, os ficheiros compilados nunca chegam à raiz servida.

**Está tudo pendente e nunca avança.** A implementação foi colocada em fila mas nunca foi processada. Despolete um **Implementar agora** manual e verifique a página Deploys para uma linha de erro.

## Para Onde Ir a Seguir

- [Pré-visualização de Implementações Para Pull Requests](https://support.kapsulehost.com/pt-pt/site-preview) acrescenta um URL por PR sobre esta configuração.
- [Armazenar Segredos de Aplicação Para Um Site](https://support.kapsulehost.com/pt-pt/site-secrets) para as credenciais de que a sua compilação e tempo de execução necessitam.
- [Registo de Atividade do Site](https://support.kapsulehost.com/pt-pt/site-activity-log) regista alterações de configuração feitas aqui.