blog
Painéis

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.

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

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
  1. O que o Git Version Control do cPanel faz, e o que ele não faz
  2. Onde criar ou clonar o repositório para não expor o .git na web
  3. Anatomia de um `.cpanel.yml` que o cPanel aceita
  4. Push atualiza o repositório, deploy executa as tasks
  5. Quando a publicação para no meio, leia o log
  6. Erros comuns e o que verificar primeiro
  7. 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:

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.

Do commit local à cópia no document rootCommit localInclui .cpanel.yml na raizPushAtualiza repositório na contaPull no servidorWorking tree recebe o branchDeployExecuta as tasks em ordemDocument rootArquivos copiados para a raiz
Push e deploy são ações separadas: empurrar commit não publica nada.

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:

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.

Triagem de falha de deploy pelo logDeploy não mudou o siteComece pelo log da execuçãoYAML inválidoTab, lista malformada, indentaçãoErro citando a origemdist/ no .gitignore, nada versionadoErro citando o destinoDocument root errado ou sem barraPermissão negadaCaminho fora da própria contaNenhuma tarefa executada.cpanel.yml ausente no branch
Ordem de checagem a partir da mensagem crua do comando no log.

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

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