blog
Painéis

Publicar do GitHub no cPanel com cron, sem webhook

Quando o push não consegue disparar o deploy, uma tarefa agendada no cPanel busca o branch e publica sozinha. O passo a passo inclui a trava contra execuções sobrepostas e o registro que mostra onde a publicação parou.

JR · · 9 min de leitura · 2 tabelas · 7 blocos de código

Resposta curta: crie no cPanel uma tarefa agendada que roda um script com o caminho absoluto do git, faz pull do branch e só chama o deploy do .cpanel.yml quando o commit muda, protegida por flock -n e gravando data e commit num log. Não há número medido aqui: o guia é documental.

Neste artigo
  1. O que a tarefa agendada resolve e quando ela faz sentido
  2. Que backup e pré-requisitos checar antes de ativar a tarefa
  3. Por que o caminho absoluto do git importa
  4. Como montar o script que só publica commit novo
  5. Como agendar a linha do cron com flock e registro em arquivo
  6. Achando a última publicação quando o site não muda
  7. Quando apagar o log e quais limites a tarefa tem

O que a tarefa agendada resolve e quando ela faz sentido

O deploy por push depende de o GitHub (ou outro serviço) conseguir avisar o servidor, ou de você empurrar o código direto para o repositório do cPanel. Há casos em que isso não acontece: o repositório é de outra pessoa, a agência não quer abrir acesso SSH para todos, o plano não permite webhook, ou você só quer que o site siga o branch main sem ninguém lembrar de publicar.

A alternativa é inverter a direção. Em vez de o GitHub avisar o servidor, o servidor pergunta ao GitHub de tempos em tempos: busca as mudanças e publica. No cPanel isso se faz com duas ferramentas que o painel já tem: o Git Version Control, que guarda o clone do repositório, e os Cron Jobs, que rodam um comando num horário fixo. O guia oficial do cPanel, Guide to Git: Set Up Deployment and Cron Jobs, descreve justamente essa combinação.

O custo dessa troca é o atraso. Se a tarefa roda a cada 15 minutos, uma correção pode levar até 15 minutos para aparecer. Se você precisa de publicação imediata, o deploy por push continua sendo a escolha certa. Se o atraso é aceitável, a tarefa agendada é mais simples de manter.

Este texto se apoia na documentação do cPanel, não em teste próprio. Caminhos de pasta, nome de usuário e nome do repositório que aparecem nos exemplos são fictícios: troque pelos seus.

Que backup e pré-requisitos checar antes de ativar a tarefa

A tarefa vai sobrescrever arquivos do site sem perguntar. Antes de ativá-la:

  1. Faça um backup completo em cPanel > Arquivos > Backup (ou na ferramenta de backup do seu plano) e baixe o arquivo para o seu computador.
  2. Confirme que o repositório já aparece em cPanel > Arquivos > Git Version Control, clonado a partir do GitHub. Anote o caminho mostrado na coluna do repositório, algo como /home/usuario/repositories/meusite.
  3. Confirme que o repositório tem um arquivo .cpanel.yml na raiz, com as tarefas de cópia para a pasta pública. É ele que diz ao cPanel o que copiar e para onde. Sem esse arquivo o painel não publica nada.
  4. Se o repositório for privado, o servidor precisa de uma chave SSH autorizada no GitHub (chave de deploy). Sem isso, a busca falha com erro de permissão, e o registro que vamos montar vai mostrar exatamente isso.

Se o seu site é WordPress, cuidado com o que está no repositório. Versione tema e plugins próprios, não a pasta wp-content/uploads nem o wp-config.php. Um deploy que copia o repositório inteiro por cima do site pode apagar ou substituir arquivos que só existem no servidor.

Como voltar atrás: basta apagar ou comentar a linha da tarefa em Cron Jobs. A publicação para na hora. Para desfazer arquivos já copiados, restaure o backup do passo 1.

Por que o caminho absoluto do git importa

O cron não roda com o mesmo ambiente do Terminal. A variável PATH, que diz onde procurar programas, costuma ser bem mais curta dentro do cron. Um comando que funciona quando você digita git pull no Terminal pode falhar na tarefa agendada com git: command not found.

A solução é chamar o binário pelo caminho completo. Para descobrir qual é, abra cPanel > Avançado > Terminal e rode:

command -v git

O resultado é uma linha com um caminho, por exemplo /usr/local/cpanel/3rdparty/bin/git ou /usr/bin/git. Esse é o caminho que vai no script. Se o comando não devolver nada, o Git não está no seu PATH do Terminal e vale perguntar ao suporte da hospedagem qual binário usar.

Faça o mesmo para o comando que dispara o deploy do cPanel:

command -v uapi

Normalmente aparece /usr/bin/uapi. Use o caminho que o seu servidor mostrar, não o do exemplo.

Como montar o script que só publica commit novo

Colocar tudo direto na linha do cron funciona, mas fica ilegível e difícil de testar. Um script curto resolve. Crie o arquivo pelo Gerenciador de Arquivos em /home/usuario/bin/deploy.sh (crie a pasta bin se não existir) com este conteúdo de exemplo:

#!/bin/bash
REPO=/home/usuario/repositories/meusite
GIT=/usr/local/cpanel/3rdparty/bin/git

echo "=== $(date '+%Y-%m-%d %H:%M:%S') inicio"
cd "$REPO" || exit 1
ANTES=$($GIT rev-parse HEAD)
$GIT pull --ff-only origin main || exit 1
DEPOIS=$($GIT rev-parse HEAD)
if [ "$ANTES" != "$DEPOIS" ]; then
  $GIT log -1 --format='commit %h %s'
  /usr/bin/uapi VersionControlDeployment create repository_root="$REPO"
else
  echo "nada novo, deploy nao disparado"
fi
echo "=== $(date '+%Y-%m-%d %H:%M:%S') fim"

Linha a linha:

Depois de salvar, clique com o botão direito no arquivo, escolha Change Permissions e marque execução para o dono (permissão 755). Teste no Terminal antes de agendar:

/home/usuario/bin/deploy.sh

O esperado é ver a linha de início, a saída do Git e a linha de fim. Se não havia nada novo, aparece Already up to date. seguido de nada novo, deploy nao disparado. Se havia commit novo, aparecem a linha commit com o hash e a mensagem e a resposta da UAPI, com o campo log_path. Para o primeiro deploy, quando o clone já está atualizado, use o botão de deploy na tela do Git Version Control. Se algo falhar aqui, vai falhar no cron também. Corrija agora.

Como agendar a linha do cron com flock e registro em arquivo

Se uma execução demora mais que o intervalo, o cron inicia a próxima enquanto a anterior ainda roda. Dois git pull simultâneos na mesma pasta disputam o repositório e podem falhar no meio. O flock impede isso: ele cria uma trava num arquivo e, com a opção -n, desiste na hora se a trava já estiver ocupada, em vez de esperar.

A trava tem um limite: ela protege o pull, não a cópia. O uapi VersionControlDeployment create só enfileira o deploy e responde na hora. A cópia do .cpanel.yml roda em segundo plano, depois que o script terminou e soltou a trava. Para saber se a cópia acabou e se deu certo, abra o arquivo indicado no campo log_path da resposta da UAPI, que fica em ~/.cpanel/logs. Como o script só dispara deploy quando entra commit novo, a chance de duas cópias se sobreporem cai, mas a trava não a elimina.

Em cPanel > Avançado > Cron Jobs:

  1. Em Cron Email, deixe um endereço só se quiser receber saída por e-mail. Como vamos gravar em arquivo, a linha abaixo não gera e-mail.
  2. Em Add New Cron Job, no menu Common Settings, escolha um intervalo. Para cada 15 minutos, preencha Minute com */15 e deixe os demais campos com *.
  3. No campo Command, cole (ajustando os caminhos):
/usr/bin/flock -n /home/usuario/deploy.lock /home/usuario/bin/deploy.sh >> /home/usuario/logs/deploy.log 2>&1
  1. Clique em Add New Cron Job.

O que cada parte faz:

Parte Função
/usr/bin/flock -n /home/usuario/deploy.lock Pega a trava no arquivo deploy.lock. Se outra execução estiver com ela, encerra sem rodar
/home/usuario/bin/deploy.sh O script de publicação
>> /home/usuario/logs/deploy.log Acrescenta a saída ao final do registro, sem apagar o que já estava lá
2>&1 Manda também as mensagens de erro para o mesmo arquivo

Crie a pasta logs antes, pelo Gerenciador de Arquivos, senão o redirecionamento falha. Confira o caminho do flock com command -v flock no Terminal, como fez com o Git.

O intervalo é escolha sua. Rodar a cada minuto não traz ganho real para a maioria dos sites e multiplica as consultas ao GitHub. Começar com 15 minutos e ajustar depois é um ponto de partida razoável.

O que acontece a cada execução da tarefaCron dispara a cada 15 minutosLinha em Cron Jobsflock pega a travaSe ocupada, encerragit pull --ff-onlyBusca o branch mainHash mudou?Compara antes e depoisuapi enfileira o deployCópia roda em segundo plano
Caminho de uma execução da tarefa, do disparo do cron até a fila de deploy do cPanel.

Achando a última publicação quando o site não muda

Você fez push, esperou, e o site continua igual. O registro responde onde a cadeia parou. No Terminal:

tail -n 30 /home/usuario/logs/deploy.log

Isso mostra as últimas 30 linhas. Para listar só os commits publicados, em ordem:

grep commit /home/usuario/logs/deploy.log | tail -n 5

Compare o hash da última linha com o hash do commit mais recente no GitHub. A partir daí, o diagnóstico segue esta tabela:

O que aparece no registro Causa provável O que fazer
Nenhuma linha nova desde o push A tarefa não está rodando, ou o caminho do redirecionamento está errado Confira a linha em Cron Jobs e se a pasta logs existe
command not found Caminho do binário errado Refaça command -v e corrija o script
Permission denied (publickey) O servidor não tem acesso ao repositório privado Cadastre a chave SSH do servidor como chave de deploy no GitHub
Not possible to fast-forward ou mensagem de divergência Commit feito dentro do repositório no servidor, ou force-push no GitHub Compare git log no servidor com o histórico no GitHub antes de descartar qualquer coisa
Your local changes ... would be overwritten Arquivo alterado sem commit dentro do repositório no servidor Veja o que mudou com git status na pasta do repositório e guarde uma cópia antes de descartar
Linha commit com o hash novo, mas site igual O pull funcionou e a cópia não Abra o arquivo indicado em log_path na resposta da UAPI (em ~/.cpanel/logs) ou o histórico de deploy na tela do Git Version Control, e revise o .cpanel.yml
Linha de início sem linha de fim O script parou no meio Leia a mensagem de erro entre as duas linhas
Hash correto e site igual mesmo assim Cache Limpe o cache do plugin do WordPress, do CDN e do navegador

Se nenhuma execução aparece por um longo período e não há erro, verifique se ficou um processo travado segurando o deploy.lock. O flock libera a trava quando o processo termina, então uma trava presa indica um script que nunca terminou, normalmente esperando senha ou confirmação. É por isso que o acesso ao GitHub precisa ser por chave, sem pergunta interativa.

Ordem para diagnosticar um deploy paradoLer as últimas linhas do logtail -n 30 no TerminalHá linha de início sem fim?Erro no meio do scriptHá linha commit com hash novo?Pull funcionouConfira o log_path da UAPIErro está na cópia do .cpanel.yml
Ordem de leitura do registro para achar onde a publicação parou.

Quando apagar o log e quais limites a tarefa tem

O arquivo deploy.log cresce a cada execução, mesmo quando nada muda, porque as linhas de início e fim são gravadas sempre. Com execução a cada 15 minutos são 96 execuções por dia. Sem commit novo, cada uma grava cerca de quatro linhas (início, saída do git, aviso de nada novo, fim), perto de 400 linhas por dia. Cada deploy acrescenta a linha commit e a resposta da UAPI, que ocupa várias linhas. Uma vez por semana, apague o arquivo pelo Gerenciador de Arquivos ou esvazie o conteúdo; a próxima execução o recria.

Alguns limites que valem saber antes de depender disso:

Se o push consegue disparar o deploy no seu caso, ele continua sendo mais rápido e mais econômico. A tarefa agendada é a saída para quando ele não consegue, e o registro com data, hash e trava é o que torna essa saída algo que você consegue depurar sozinho.

Referências

  1. Documentação oficial (cpanel) — Guide to Git: Set Up Deployment and Cron Jobs. Consultado em 2026-10-29.
Leia também