Sites
Implementar um Site a Partir de Git
Git Deploy connects a repository to a site so that every push to your chosen branch clones the code, runs your build, and publishes the result. This guide covers the initial connection, the two…
Git Deploy conecta um repositório a um site para que cada push para o seu branch escolhido clone o código, execute o build e publique o resultado. Este guia cobre a conexão inicial, os dois passos do lado do repositório que finalizam a configuração, a leitura do histórico de deploy e a detecção de buildpack que decide como uma aplicação Node.js é construída.
Onde Git Deploy Se Localiza
Abra Websites, clique no site, abra o menu Advanced na fita de abas do site e escolha Git Deploy. Duas páginas relacionadas ficam no mesmo menu:
- Deploys, o histórico de deploy completo para este site.
- Buildpack, a estratégia de build detectada, em sites Node.js.
A página Git Deploy descreve-se claramente: conecte um repositório e cada push para o seu branch configurado dispara um build e deploy.
Conectar um Repositório
- Escolha o seu Provider: GitHub, GitLab ou Bitbucket.
- Introduza o Repository URL. O formulário SSH é o que você quer, por exemplo
git@github.com:user/repo.git. - Defina o Branch a partir do qual fazer deploy. O campo começa em
main. - Opcionalmente defina um Build command, por exemplo
npm run build. - Opcionalmente defina um Output directory, por exemplo
dist,public, ou.para um repositório que já está construído. - Clique Connect repo.
Deixe o comando de build e o diretório de saída vazios se o seu repositório já é implementável tal como está, que é o caso comum para um site PHP simples ou estático.
Advanced Scripts
Expandir Advanced revela dois campos extra:
- Pre-deploy script, que executa antes do build.
- Post-deploy script, que executa após o deploy.
Use o gancho de pós-deploy para as coisas que têm de acontecer uma vez que o novo código está no lugar: limpar uma cache de aplicação, executar uma migração de base de dados, reiniciar um worker.
Auto-Deploy On Push
O toggle na parte inferior do cartão controla se os pushes fazem deploy. Quando está ligado, cada push para o branch configurado dispara um deploy. Quando está desligado, os deploys apenas são executados quando você os dispara manualmente com Deploy now.
Desative o auto-deploy durante um code freeze ou um incidente em vez de desconectar o repositório. Desconectar destrói a chave de deploy e o segredo do webhook, portanto você tem de refazer ambos os passos do lado do repositório depois.
Finalizar a Configuração No Seu Repositório
Conectar o repositório em KPanel é apenas o primeiro de três passos. Até que um deploy tenha sido executado, a página mostra um banner com a leitura Complete setup: 2 steps remaining com tudo o que você precisa.
Passo 2: Adicionar a Deploy Key
Kapsule precisa de acesso de leitura para clonar o seu repositório. O banner mostra uma chave pública com um botão Copy key.
Cole-a nas chaves de deploy do seu repositório. Para GitHub o banner oferece um atalho Add to GitHub direto para a página de configurações correta. O acesso de leitura é suficiente, não conceda escrita.
Passo 3: Adicionar o Webhook
O webhook é o que diz a Kapsule que um push aconteceu. O banner dá-lhe três valores:
| Campo | Valor |
|---|---|
| Payload URL | Uma URL terminando em /api/git-deploy/webhook/ mais o ID deste site |
| Secret | Um segredo de assinatura gerado, oculto até você clicar no ícone de olho |
| Content Type | application/json |
Copie cada um para as configurações de webhook do seu repositório. Para GitHub existe um atalho Add webhook to GitHub. Defina o tipo de conteúdo como JSON, não a codificação de formulário padrão, ou o payload não será interpretado.
Trate o segredo do webhook como uma senha. Qualquer pessoa que o tenha, mais a URL de payload, pode disparar um deploy do seu site. Ambos os valores são apenas mostrados a pessoas que já podem administrar o site, e o segredo permanece oculto atrás do ícone de olho até você pedir.
Fazer Deploy Manualmente
Clique Deploy now na página Git Deploy para construir e fazer deploy do head atual do branch configurado sem fazer push de um commit. Isto funciona quer o auto-deploy esteja ligado ou não, o que torna isto a ferramenta certa durante um freeze: os pushes são ignorados, mas você ainda pode entregar a correção.
Ler Histórico de Deploy
Abra Advanced, depois Deploys. A página é intitulada Deploy history e lista cada implementação acionada por webhook ou manualmente, mais recente primeiro.
Cada linha contém:
- Um ícone de estado e o SHA de commit curto, com o branch como um pill.
- A mensagem de commit, ou Manual deploy se não havia uma mensagem de commit para mostrar.
- O autor, há quanto tempo foi executado, quanto tempo demorou, e o que o acionou.
- Um pill de estado.
Os estados são pending, building, deploying, success e failed. Enquanto algo estiver em andamento, a página atualiza-se a cada cinco segundos e mostra uma nota Refreshing automatically sob a tabela, para que você possa deixá-la aberta e observar um deploy.
Quando um Deploy Falha
Uma linha falhada obtém um botão Error à direita. Clique para expandir a saída de erro capturada inline, sem sair da página. Essa saída é o texto de erro do próprio build, portanto geralmente nomeia o ficheiro ou o comando que falhou.
Trabalhe através dele nesta ordem: leia o erro, reproduza o mesmo comando de build localmente, corrija, faça push. Se o build funciona localmente mas não aqui, a diferença é quase sempre um ambiente, uma dependência em falta que está instalada globalmente na sua máquina, ou um ficheiro que está no seu diretório de trabalho mas não foi committed.
Detecção de Buildpack
Em sites Node.js, a página Buildpack no menu Advanced mostra como Kapsule decidiu construir a sua app. A detecção é executada sobre os ficheiros na raiz do seu repositório, e a primeira correspondência vence:
| Detectado | Trigger |
|---|---|
| Custom buildpack | kapsule.config.yaml ou kapsule.config.yml na raiz |
| Dockerfile buildpack | Dockerfile na raiz |
| Node.js | package.json com um script start, build ou dev |
| Python | requirements.txt ou pyproject.toml |
| PHP | composer.json |
| Static | index.html na raiz |
Se nada corresponder, a página diz isto e lista os triggers suportados. Adicione um Dockerfile ou um kapsule.config.yaml para tomar controlo do build explicitamente.
Executar um Build
Clique Run build para enfileirar um. A página faz polling a cada três segundos enquanto um run está em andamento, e a tabela Recent builds mostra os últimos runs com a sua hora de início, tipo, estado, duração e referência de imagem resultante. Clique numa linha para ver o seu log tail.
Apenas um build pode estar em andamento por vez. Acionar um segundo enquanto um está enfileirado ou em execução é recusado com A build is already in progress, o que é deliberado: dois builds escrevendo a mesma saída ao mesmo tempo é como você obtém um site meio-implementado.
Desconectar
Clique Disconnect e confirme. A confirmação é explícita sobre o raio de explosão: a configuração de Git deploy e a chave de deploy são removidas, e os ficheiros do seu site não são afetados. O site continua a servir o que foi implementado por último.
Arrume depois eliminando a chave de deploy e o webhook nas configurações do seu repositório. Eles simplesmente deixarão de funcionar, mas deixar entradas mortas por aí torna a próxima auditoria mais difícil.
Resolução de Problemas
Os pushes não disparam nada. Verifique o toggle auto-deploy primeiro, depois o webhook no seu repositório. A maioria dos providers mostra entregas recentes e os seus códigos de resposta, o que lhe diz imediatamente se o pedido saiu do seu repositório.
O cloning falha. A chave de deploy está em falta, foi colada com uma quebra de linha nela, ou foi adicionada ao repositório errado. Copie-a novamente com o botão Copy key em vez de selecionar o texto manualmente.
O deploy sucede mas o site não muda. O diretório de saída é provavelmente errado. Se o seu build escreve em dist e o diretório de saída está vazio, os ficheiros construídos nunca chegam à raiz servida.
Tudo diz pending e nunca se move. O deploy foi enfileirado mas nunca foi apanhado. Dispare um Deploy now manual e verifique a página Deploys para uma linha de erro.
Para Onde Ir A Seguir
- Preview Deploys For Pull Requests adiciona um URL por-PR em cima desta configuração.
- Storing App Secrets For a Site para as credenciais que o seu build e runtime precisam.
- Site Activity Log registra as mudanças de configuração feitas aqui.