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.
Ligar um Repositório
- Escolha o seu Provider: GitHub, GitLab ou Bitbucket.
- Introduza o URL do Repositório. A forma SSH é a que pretende, por exemplo
git@github.com:user/repo.git. - Defina o Branch a partir do qual implementar. O campo começa em
main. - Opcionalmente, defina um Comando de compilação, por exemplo
npm run build. - Opcionalmente, defina um Diretório de saída, por exemplo
dist,public, ou.para um repositório que já esteja compilado. - 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.
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.
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 acrescenta um URL por PR sobre esta configuração.
- Armazenar Segredos de Aplicação Para Um Site para as credenciais de que a sua compilação e tempo de execução necessitam.
- Registo de Atividade do Site regista alterações de configuração feitas aqui.