Implementar o Laravel a partir do GitHub com Git e o .cpanel.yml do cPanel

Este guia explica o fluxo manual do Git e do .cpanel.yml do cPanel para uma aplicação Laravel. Se quiser gerir repositórios, scripts, versões e webhooks a partir da área de cliente, utilize o Deploy+.

O exemplo do cPanel atualiza um clone de trabalho. Não cria por si só releases isoladas nem garante que o site se mantenha sem interrupções durante uma atualização.

Preparar o acesso e o projeto

Ative o SSH e prepare uma chave dedicada de leitura para o repositório privado. Verifique a impressão digital do GitHub e evite reutilizar uma identidade com acesso a outros projetos.

Trabalhe primeiro com um domínio e uma base de dados de testes. O repositório deve incluir o código e o composer.lock, mas não palavras-passe, o .env de produção nem ficheiros carregados pelos utilizadores.

Em cPanel > Git Version Control > Create, introduza o URL SSH, um caminho privado como ~/repositories/laravel (substitua ~ pelo diretório da sua conta se o formulário exigir um caminho absoluto) e um nome identificativo. Se utilizar um alias SSH para a chave, use-o também no URL do clone.

Verifique o ramo e o conteúdo antes de configurar a implementação.

Definir as tarefas

Crie o .cpanel.yml na raiz do repositório. Para manter as verificações juntas e parar o processo se um comando falhar, chame um script versionado:

---
deployment:
  tasks:
    - /bin/bash /home/usuario_cpanel/repositories/laravel/deploy/cpanel.sh

Um exemplo de deploy/cpanel.sh seria:

#!/bin/bash
set -euo pipefail
cd /home/usuario_cpanel/repositories/laravel

PHP_BIN=/opt/alt/php83/usr/bin/php
COMPOSER_BIN=/opt/cpanel/composer/bin/composer

test -x "$PHP_BIN"
test -f "$COMPOSER_BIN"
test -f composer.lock
test -f .env

"$PHP_BIN" "$COMPOSER_BIN" install --no-dev --no-interaction --prefer-dist --optimize-autoloader
"$PHP_BIN" artisan config:cache
"$PHP_BIN" artisan view:cache
"$PHP_BIN" artisan route:cache

Substitua o utilizador e confirme os caminhos do PHP e do Composer na sua conta. O PHP 8.3 é apenas o valor do exemplo: o interpretador de consola tem de ser compatível com a sua aplicação e com a versão que serve o site. Não utilize composer update para resolver dependências diretamente em produção.

Prepare o .env privado, a base de dados e os diretórios persistentes antes de executar o script. Se migrar uma aplicação existente, mantenha a sua APP_KEY. Configure APP_DEBUG=false. Acrescente a compilação de recursos que o projeto exigir, ou publique-os já compilados a partir de um ambiente compatível.

As migrações da base de dados precisam do seu próprio plano testado. Não estão incluídas aqui automaticamente: uma falha do código não desfaz uma migração nem recupera dados.

Publicar apenas a pasta public

O Laravel deve ser exposto através da sua pasta public, não da raiz do repositório. Reveja a raiz de documentos do domínio e os caminhos que o servidor permite.

Para um domínio adicional ou subdomínio, utilize um caminho admitido pelo cPanel. Se o domínio principal exigir manter o public_html, prepare a publicação adequada com o suporte ou com a ferramenta de implementação. Não apague nem mude o nome de toda essa pasta sem rever outros sites, ficheiros e serviços que dependam dela.

Antes de alterar a publicação, guarde uma cópia do site e da base de dados e combine como recuperar o destino anterior. Teste primeiro o projeto na sua localização de ensaio.

Atualizar e implementar

No repositório do cPanel, abra Manage > Pull or Deploy:

1. Execute Update from Remote para obter o código.
2. Verifique o commit e o ramo.
3. Execute Deploy HEAD Commit para as tarefas do .cpanel.yml.
4. Acompanhe o registo até ao fim e teste o site.

Atualizar a partir do remoto e executar as tarefas são operações distintas. Se o site servir diretamente o clone, o primeiro passo já pode alterar ficheiros visíveis, mesmo que ainda não tenha executado o segundo.

O pedido equivalente de implementação local é:

/usr/local/cpanel/bin/uapi --output=jsonpretty VersionControlDeployment create \
  repository_root='/home/usuario_cpanel/repositories/laravel'

Um result.status igual a 1 confirma que o cPanel aceitou o pedido. Consulte a tarefa e o seu log_path até conhecer o resultado final; não o interprete como «a aplicação já funciona».

Automatizar sem sobrepor tarefas

Um push para o GitHub não inicia por si só o pull do cPanel. Para o automatizar, precisa de um recetor ou de um processo que o programe. O Deploy+ oferece essa integração sem ter de construir o recetor.

Se mantiver um próprio, valide a assinatura do fornecedor, o repositório e o ramo antes de colocar trabalho em fila. Utilize comandos e caminhos definidos na sua configuração e mantenha um bloqueio até que a implementação termine realmente. Bloquear apenas a chamada que coloca uma tarefa em fila não evita que duas tarefas posteriores se sobreponham.

Não publique um URL que execute comandos ao ser visitado e não passe o conteúdo do webhook diretamente para a shell. Registe a entrega, o commit e o resultado sem segredos.

Validar e recuperar

Teste a página inicial, um caminho dinâmico, a autenticação, os formulários e os recursos. Reveja os registos e os processos que devam carregar o código novo. Se a implementação falhar, identifique que tarefas chegaram a ser executadas antes de a repetir.

Recuperar um diretório ou um commit anterior não reverte bases de dados, o .env nem ficheiros partilhados. Para atualizações frequentes que precisem de alternar versões, considere o Deploy+ ou uma estratégia de releases com uma reversão testada.