Publicar site por Git no cPanel com .cpanel.yml
O ciclo completo do Git Version Control do cPanel, do lado de quem dá push: onde criar o repositório, como escrever o .cpanel.yml e como ler o log quando o deploy para no meio.

Resposta curta: publique criando ou clonando o repositório fora do document root, com um `.cpanel.yml` válido (chave `deployment`, lista `tasks`, caminhos absolutos em /home/usuario e `/bin/cp -R`) no branch em checkout. O push atualiza o repositório; o deploy executa as tasks.
Neste artigo
- O que o Git Version Control do cPanel faz, e o que ele não faz
- Onde criar ou clonar o repositório para não expor o .git na web
- Anatomia de um `.cpanel.yml` que o cPanel aceita
- Push atualiza o repositório, deploy executa as tasks
- Quando a publicação para no meio, leia o log
- Erros comuns e o que verificar primeiro
- Backup, reversão e o que fica fora deste escopo
O que o Git Version Control do cPanel faz, e o que ele não faz
O recurso Git Version Control do cPanel hospeda repositórios Git dentro da sua própria conta, no seu /home/usuario. Você empurra commits para esse repositório e o cPanel executa, no servidor, uma lista de tarefas que você mesmo escreveu em um arquivo chamado .cpanel.yml. É isso: um repositório remoto com um hook de deploy declarativo.
O que ele não é: não é um build server, não é CI. Não há etapa de instalação de dependências implícita, não há cache de artefatos, não há rollback automático. Se o seu projeto precisa de npm run build, o build acontece antes, na sua máquina ou no seu pipeline, e o que você versiona ou publica é o resultado. As tarefas do .cpanel.yml são comandos de cópia e preparação, executados com o usuário da conta cPanel.
E um detalhe que decide o resultado: o deploy só roda se o repositório tiver .cpanel.yml no branch que está em checkout no servidor, não no branch que você considera principal na sua cabeça. Isso está descrito no Guide to Git: Set Up Deployment and Cron Jobs do cPanel e é a origem silenciosa de boa parte das publicações que "não acontecem".
Onde criar ou clonar o repositório para não expor o .git na web
No cPanel, em *Files > Git Version Control*, você tem duas rotas:
- Criar: o cPanel inicializa um repositório vazio em um diretório da conta.
- Clonar: você informa uma URL de origem e o cPanel traz o histórico para dentro da conta.
A decisão que mais importa aqui é onde o repositório vive. Não coloque o repositório diretamente no document root. Se o .git e os arquivos de trabalho ficarem em public_html, você expõe histórico, arquivos de configuração e tudo que o build não deveria publicar. O padrão saudável é: repositório fora da raiz web, e o .cpanel.yml copia para dentro dela.
Um layout de exemplo, para adaptar ao seu usuário e ao seu domínio:
/home/usuario/repositories/meusite <- repositório (working tree + .git)
/home/usuario/public_html <- document root do domínio principal
/home/usuario/meusite.com.br <- document root de um addon domain (exemplo)
Confirme o document root real do domínio em *Domains* antes de escrever qualquer caminho. Subdomínio e addon domain quase nunca apontam para public_html, e copiar para o lugar errado é um deploy que "deu certo" sem mudar nada no site.
Anatomia de um `.cpanel.yml` que o cPanel aceita
O arquivo fica na raiz do repositório, é YAML, e a documentação do cPanel define a estrutura: uma chave deployment, dentro dela tasks, e dentro de tasks uma lista de comandos executados em ordem.
Exemplo mínimo, para adaptar (troque usuario e os caminhos pelos seus):
---
deployment:
tasks:
- export DEPLOYPATH=/home/usuario/public_html/
- /bin/cp -R dist/* $DEPLOYPATH
As regras que mais derrubam deploy:
| Regra | Por quê |
|---|---|
| Indentação com espaços, nunca tab | YAML rejeita tabulação; o editor que converte espaço em tab quebra o arquivo em silêncio |
Caminhos absolutos em /home/usuario/... |
O diretório de trabalho da tarefa não é garantidamente o que você imagina |
Comandos com caminho absoluto (/bin/cp -R) |
A documentação do cPanel usa essa forma nos exemplos; evita depender do PATH do contexto de execução |
Barra final no DEPLOYPATH |
cp -R origem/* /destino/ tem semântica previsível quando o destino existe e termina em barra |
| Arquivo presente no branch em checkout | Sem .cpanel.yml nesse branch, não há deploy, e não há erro gritando com você |
Se você precisa publicar vários diretórios, some tarefas em vez de escrever um comando gigante:
---
deployment:
tasks:
- export DEPLOYPATH=/home/usuario/public_html/
- /bin/cp -R public/* $DEPLOYPATH
- /bin/mkdir -p $DEPLOYPATH/assets
- /bin/cp -R assets/. $DEPLOYPATH/assets/
- /bin/cp .htaccess $DEPLOYPATH
Repare na terceira e na quarta tarefa. cp -R assets /destino/ só copia o diretório para dentro do destino na primeira vez; quando /destino/assets já existe, o próprio cp passa a tratar o destino existente como pai e cria /destino/assets/assets, ou seja, o segundo deploy publica no lugar errado. A forma cp -R assets/. /destino/assets/ copia o conteúdo do diretório, é idempotente e falha cedo se o destino não existir, por isso o mkdir -p antes.
Cada linha é um passo. Quando um passo falha, o log aponta o passo, e isso vale mais do que elegância.
Validar o YAML com um comando, antes do commit
Um commit só para descobrir que a indentação está errada é um ciclo caro. Valide localmente com qualquer parser de YAML que você já tenha instalado:
python3 -c "import yaml,sys; print(yaml.safe_load(open('.cpanel.yml')))"
Se isso imprime um dicionário com deployment e uma lista em tasks, a sintaxe está de pé. Continua sendo necessário conferir se os caminhos existem no servidor, o que o parser não sabe.
Push atualiza o repositório, deploy executa as tasks
Com o repositório criado no cPanel, o fluxo local é o de sempre. O cPanel mostra a URL de clone SSH do repositório na própria tela do Git Version Control; use a sua, o trecho abaixo é um exemplo de formato.
# clonar o repositório hospedado na conta (exemplo de URL)
git clone ssh://[email protected]/home/usuario/repositories/meusite
cd meusite
git checkout main
# edite, adicione o .cpanel.yml na raiz
git add .cpanel.yml
git commit -m "adiciona pipeline de deploy"
git push origin main
O push atualiza o repositório na conta. A partir daí, a publicação é acionada na interface do cPanel, em *Git Version Control > Manage > Pull or Deploy*, onde existem as ações de atualizar o working tree a partir do remoto e de executar o deploy descrito no .cpanel.yml. O ponto importante é entender a separação: push atualiza o repositório; deploy executa as tasks. Confundir os dois é achar que o site deveria ter mudado quando ninguém mandou copiar nada.
Se nada acontece na hora de executar o deploy, a checagem é curta: o branch em checkout no servidor é o mesmo que você empurrou, e .cpanel.yml existe nele.
Quando a publicação para no meio, leia o log
O cPanel registra a execução do deploy do repositório e expõe esse registro na própria interface do Git Version Control, junto com as informações da última publicação. É ali que você descobre em qual tarefa o processo parou e qual foi a mensagem do comando.
A documentação citada no fim deste texto descreve a leitura pela interface e não publica o caminho do arquivo de log dentro da conta, então não vou afirmar um caminho fixo: ele varia com a versão do cPanel e com a configuração do servidor. Por SSH, o jeito confiável de achar o arquivo da sua conta é procurar pelos registros gravados nos últimos minutos depois de disparar um deploy:
# logo após executar o deploy pela interface
find ~ -xdev -type f -mmin -5 -name '*deploy*' 2>/dev/null
find ~/.cpanel -xdev -type f -mmin -5 2>/dev/null
Achado o arquivo, o acompanhamento é o de sempre, tail -f caminho/do/arquivo.log. O que a interface mostra e o que o arquivo guarda é a saída crua dos comandos das tasks, no formato que o shell produziu. Uma falha típica aparece assim:
Processing task: /bin/cp -R dist/* /home/usuario/public_html/
/bin/cp: cannot stat 'dist/*': No such file or directory
Task failed with exit code 1
O texto exato das linhas de controle muda entre versões; a linha do meio é a do cp e é ela que importa. Não medi isso em bancada: é leitura de saída de comando, não benchmark.
Ler o log muda o diagnóstico de adivinhação para leitura. Alguns padrões que o próprio texto do erro entrega:
- Mensagem de *no such file or directory* citando o destino: o document root do caminho de destino não é o que você escreveu, ou falta a barra final.
- Mensagem de *no such file or directory* citando a origem: o diretório que o build deveria gerar não está versionado. Clássico de
dist/dentro do.gitignore. - Mensagem de permissão negada: o caminho de destino pertence a outro contexto, ou você está tentando escrever fora da própria conta.
- Deploy que termina sem copiar nada: o glob não casou com arquivo algum.
Quando o problema é o próprio arquivo, o cPanel sinaliza que o .cpanel.yml é inválido em vez de executar tarefas pela metade. Nesse caso, o erro não está no servidor: está na sintaxe. Volte ao parser local, corrija a indentação, commit, push.
Erros comuns e o que verificar primeiro
| Sintoma | Verificação |
|---|---|
| Push ok, site inalterado | O deploy foi executado? .cpanel.yml está no branch em checkout? |
| Deploy acusa YAML inválido | Tab no lugar de espaço; tasks não é lista; falta o --- ou a indentação sob deployment |
| Copia para o lugar errado | Document root do domínio conferido em *Domains*; addon e subdomínio não usam public_html |
| Origem não encontrada | Diretório de build está no .gitignore e nunca chegou ao servidor |
| Arquivos ocultos não publicados | * não casa com .htaccess; copie o arquivo explicitamente |
| Repositório exposto na web | Repositório criado dentro do document root; mova para fora e publique por cópia |
Backup, reversão e o que fica fora deste escopo
O deploy aqui é destrutivo por natureza: cp -R sobrescreve o que está no destino e não remove o que sobrou de versões anteriores. Duas consequências práticas. Primeira: arquivo deletado no repositório continua vivo no document root até alguém apagar. Segunda: se o site tem diretório de uploads dentro da raiz, ele não é tocado pelo cp, mas também não está versionado, então ele não volta de um git checkout. Faça backup antes do primeiro deploy em um site que já está no ar.
Reverter é empurrar o estado anterior e publicar de novo. Como o repositório é a fonte, git revert do commit problemático seguido de push e deploy devolve os arquivos. O que não volta sozinho é banco de dados e o que foi gerado em runtime.
Duas coisas ficam deliberadamente fora deste texto: chamadas de API e agendamento de deploy por tarefa agendada. A sintaxe correta varia conforme o contexto de execução e o ambiente da conta, e um exemplo errado aqui custaria mais do que a ausência dele. Para esses pontos, a referência é a documentação do cPanel: Guide to Git: Set Up Deployment and Cron Jobs, consultada em 16/09/2026. Todo YAML, caminho e URL mostrados acima são exemplos para adaptar ao seu usuário, ao seu domínio e ao seu servidor.
Referências
- Documentação oficial (cpanel) — Guide to Git: Set Up Deployment and Cron Jobs. Consultado em 2026-09-16.