# 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.

> 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.

João Rizzon · 2026-11-11 · Painéis

---

## 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](https://docs.cpanel.net/knowledge-base/web-services/guide-to-git-set-up-deployment-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:

- 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.
- 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`.
- 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.
- 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:

- `REPO` e `GIT` guardam o caminho do repositório e do binário. Troque pelos que você anotou.
- O primeiro `echo` grava data e hora do início. É isso que permite achar cada execução depois.
- `cd "$REPO" || exit 1` entra na pasta do repositório e encerra o script se ela não existir.
- `ANTES` e `DEPOIS` guardam o hash do commit ativo antes e depois do pull. É o que `rev-parse HEAD` devolve.
- `pull --ff-only` busca o branch `main` e só aceita avançar em linha reta. Se o histórico divergiu (alguém fez commit dentro do repositório no servidor, ou alguém fez force-push no GitHub), o comando falha em vez de criar um merge silencioso. Se há arquivo alterado sem commit no repositório do servidor, ele também para, com outra mensagem. Troque `main` pelo nome do seu branch.
- O `if` compara os dois hashes. Se mudou, grava a linha `commit` com hash e mensagem e chama a UAPI. Se não mudou, grava `nada novo` e não copia nada. Sem essa checagem, a cópia por cima do site se repetiria 96 vezes por dia sem necessidade.
- `uapi VersionControlDeployment create` pede ao cPanel que execute as tarefas do `.cpanel.yml`, o mesmo que o botão de deploy faz na tela do Git Version Control. Ela só coloca o deploy na fila: responde na hora com um campo `log_path`, e a cópia acontece em segundo plano.

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**:

- 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.
- 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 `*`.
- 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
```

- 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.

## 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.

## 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:

- A tarefa publica o que está no branch, sem revisão. Um commit quebrado vai para o ar no próximo ciclo. Proteja o branch no GitHub ou publique a partir de um branch separado, como `producao`.
- O deploy roda com o seu usuário do cPanel. Ele só consegue escrever onde você mesmo consegue.
- Banco de dados não acompanha. Mudanças de configuração do WordPress que vivem no banco continuam sendo feitas pelo painel.

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.

