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

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

João Rizzon · 2026-10-02 · Painéis

---

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

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

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

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

```bash
# clonar o repositório hospedado na conta (exemplo de URL)
git clone ssh://usuario@servidor.exemplo.com.br/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:

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

