Site de teste e produção com Git no cPanel, passo a passo
Como montar produção e teste na mesma conta cPanel com Git Version Control, cada branch publicando na sua pasta, e o que fazer quando alguém editou arquivo direto no servidor.

Resposta curta: Crie dois repositórios no Git Version Control do cPanel, clonados do mesmo remoto: um com main publicando em public_html e outro com develop publicando no subdomínio de teste, cada um com seu próprio .cpanel.yml. Antes de trocar de branch, guarde as edições feitas no servidor com git stash.
Neste artigo
Como a montagem funciona
A ideia é simples de descrever e fácil de errar na prática. Você tem um repositório remoto (no GitHub, GitLab ou similar) com dois branches: main, que é o site no ar, e develop, que é a versão de teste. Na mesma conta cPanel você cria dois repositórios gerenciados pela interface Git Version Control, clonados do mesmo remoto, cada um em uma pasta própria e cada um com um branch diferente em checkout.
Cada repositório publica para um lugar diferente: o de produção copia os arquivos para a raiz do domínio principal (public_html), e o de teste copia para a raiz do subdomínio (por exemplo, teste.seudominio.com.br). Quem decide o destino é o arquivo .cpanel.yml que está dentro de cada branch, conforme o guia de configuração avançada do Git no cPanel.
Os caminhos abaixo são exemplos. Troque usuario e o domínio pelos seus.
| Papel | Pasta do repositório (exemplo) | Branch em checkout | Pasta publicada (exemplo) |
|---|---|---|---|
| Produção | /home/usuario/repositorios/site-producao |
main |
/home/usuario/public_html |
| Teste | /home/usuario/repositorios/site-teste |
develop |
/home/usuario/teste.seudominio.com.br |
Repare que os repositórios ficam fora de public_html. Assim a pasta .git não fica acessível pelo navegador, e o que vai ao ar é só o que o .cpanel.yml manda copiar.
Um ponto que muda tudo para quem usa WordPress: o Git versiona arquivos (tema, plugin próprio, código). Ele não leva o banco de dados. Post, página, configuração de plugin e usuário ficam no MySQL e não passam de teste para produção por esse caminho.
Antes de começar: backup e o subdomínio de teste
Nenhum passo desta montagem apaga o site sozinho, mas um .cpanel.yml apontando para a pasta errada sobrescreve arquivos de produção na primeira publicação. Faça o backup antes.
- No cPanel, abra Gerenciador de Arquivos, selecione a pasta
public_html, clique com o botão direito e escolha Compress (Compactar). Baixe o.zipgerado para o seu computador. - Se o site é WordPress, exporte o banco em phpMyAdmin, aba Exportar, método Personalizado, formato SQL. Na parte de opções de criação de objetos, marque Adicionar declaração DROP TABLE. Sem essa opção, o arquivo não consegue ser importado por cima das tabelas que já existem.
- Para voltar atrás: no phpMyAdmin, selecione o banco, aba Importar, envie o
.sql. Se a exportação foi feita no método rápido, sem DROP TABLE, apague antes todas as tabelas do banco (aba Estrutura, marcar todas, Eliminar) ou importe num banco vazio. Nos arquivos, o.zipgerado contém a própria pastapublic_html, então ele deve ser enviado e extraído em/home/usuario(a pasta acima), nunca dentro depublic_html. Extrair por cima restaura o que existia, mas não remove arquivos criados depois do backup. Para voltar ao estado exato, apague o conteúdo depublic_htmle só então extraia o.zipem/home/usuario. Depois de extrair, abrapublic_htmle confira que não surgiu uma pastapublic_html/public_html. Se surgiu, a extração foi feita no lugar errado.
Depois crie o subdomínio de teste em Domínios (ou Subdomínios, conforme a versão do painel). Anote a raiz do documento que o cPanel sugerir: é esse caminho que vai no .cpanel.yml do branch de teste. Se o teste usa WordPress, ele precisa de uma instalação separada, com banco próprio e wp-config.php próprio. Instale pelo instalador de aplicativos do painel (WordPress Toolkit ou Softaculous, conforme o que o seu cPanel oferecer), escolhendo o subdomínio de teste como destino: o instalador cria o banco e o wp-config.php sozinho. Faça isso antes do primeiro deploy, porque o .cpanel.yml copia o tema para wp-content/themes/ e essa pasta só existe depois da instalação. Apontar o site de teste para o banco de produção faz cada clique no teste alterar o site no ar.
Criando os dois repositórios no cPanel
Clonar o repositório de produção
No cPanel, vá em Arquivos > Git Version Control e clique em Create. Ative a opção de clonar um repositório, cole a URL do remoto em Clone URL, preencha Repository Path com repositorios/site-producao e dê um nome em Repository Name, como Produção. Clique em Create.
Se o remoto é privado, o servidor precisa de uma chave SSH autorizada nele antes do clone. Sem isso, o clone falha por permissão. O caminho:
- No cPanel, abra Segurança > Acesso SSH > Gerenciar chaves SSH e clique em Gerar nova chave. Deixe a senha da chave em branco, porque o clone pelo painel não tem onde digitá-la.
- Na lista Chaves públicas, clique em Exibir/Baixar na chave criada e copie o texto inteiro.
- No GitHub, abra o repositório, Settings > Deploy keys > Add deploy key e cole. No GitLab, Settings > Repository > Deploy keys.
- Volte ao Git Version Control e use a Clone URL no formato SSH, que começa com
git@(por exemplo,[email protected]:usuario/repositorio.git). A URLhttps://não usa a chave.
Clonar o mesmo remoto para o teste
Repita o processo com a mesma URL, mas com Repository Path igual a repositorios/site-teste e nome Teste. São duas cópias independentes do mesmo histórico.
Colocar develop no checkout do repositório de teste
O branch develop precisa existir no remoto antes de aparecer na lista do painel. Se ele ainda não existe, crie a partir de main no seu computador. Abra o terminal (no Windows, o Git Bash) dentro da pasta do projeto clonado e rode:
git checkout main
git checkout -b develop
git push -u origin develop
A primeira linha garante que você parte de main (resposta: Switched to branch 'main' ou Already on 'main'). A segunda cria develop e muda para ele (Switched to a new branch 'develop'). A terceira envia o branch novo ao remoto; a resposta termina com branch 'develop' set up to track 'origin/develop'. Se develop já existe, pule este bloco.
De volta ao cPanel, na lista do Git Version Control, clique em Manage no repositório Teste, abra a aba Pull or Deploy e clique em Update from Remote, para que o servidor fique sabendo do branch novo. Depois, na aba Basic Information, no campo Checked-Out Branch, escolha develop e salve. Se develop não aparecer na lista, recarregue a página e confira no GitHub ou GitLab se o push acima chegou ao remoto. O de produção fica em main. A partir daí, o botão Update from Remote (aba Pull or Deploy) de cada repositório puxa só o branch que está em checkout nele.
Criar o .cpanel.yml em cada branch
Sem o arquivo .cpanel.yml na raiz do branch, o botão Deploy HEAD Commit fica indisponível e nada é publicado. Por isso este passo vem antes da publicação.
No seu computador, no terminal aberto na pasta do projeto, mude para o branch de teste com git checkout develop (resposta: Switched to branch 'develop' ou Already on 'develop').
Crie o .cpanel.yml na raiz do projeto com o conteúdo de teste (seção Um .cpanel.yml diferente em cada branch, logo abaixo) e envie:
git add .cpanel.yml
git commit -m "Deploy do teste"
git push
O add marca o arquivo para o próximo commit e não responde nada. O commit grava a mudança; a resposta mostra 1 file changed. O push envia ao remoto e termina com uma linha como develop -> develop.
Agora volte para main. O arquivo some da pasta, porque ele só existe em develop. Crie de novo o .cpanel.yml, agora com o destino em public_html, e envie:
git checkout main
git add .cpanel.yml
git commit -m "Deploy de producao"
git push
Aqui o push termina com main -> main. Quem prefere não usar terminal faz o mesmo no site do GitHub: escolha o branch no seletor acima da lista de arquivos, clique em Add file > Create new file, digite .cpanel.yml como nome, cole o conteúdo e clique em Commit changes.
Em seguida, clique em Update from Remote nos dois repositórios do cPanel para que eles recebam o arquivo.
Publicar o teste antes da produção
Na mesma aba Pull or Deploy, o botão Deploy HEAD Commit executa as tarefas do .cpanel.yml daquele branch. Publique primeiro o de teste, abra o subdomínio no navegador e confira se nada caiu em public_html por engano.
Por que cada branch precisa de um .cpanel.yml diferente
O .cpanel.yml fica na raiz do repositório e é versionado como qualquer arquivo. A sintaxe completa está na documentação do cPanel; aqui interessa só o destino. Exemplo para o branch develop, publicando um tema:
---
deployment:
tasks:
- export DEPLOYPATH=/home/usuario/teste.seudominio.com.br/wp-content/themes/
- /bin/cp -R meu-tema $DEPLOYPATH
No branch main, o mesmo arquivo muda só a linha do destino:
---
deployment:
tasks:
- export DEPLOYPATH=/home/usuario/public_html/wp-content/themes/
- /bin/cp -R meu-tema $DEPLOYPATH
Aqui mora a armadilha principal desta montagem. Quando você faz merge de develop em main no seu computador, o Git pode trazer junto o .cpanel.yml do teste. O próximo deploy de produção passa a copiar para o subdomínio, e o site principal para de receber atualização sem dar erro nenhum.
Para levar o que foi testado em develop para produção, no seu computador:
git checkout main
git pull
git merge develop
A primeira linha muda para main. A segunda baixa o que houver de novo no remoto (Already up to date. se não houver nada). A terceira junta develop em main e lista os arquivos alterados. Se aparecer CONFLICT no .cpanel.yml (comum no primeiro merge, porque os dois branches criaram o arquivo), abra o arquivo, mantenha só a linha com public_html, apague as marcas <<<<<<<, ======= e >>>>>>> e rode git add .cpanel.yml seguido de git commit. Depois da conferência abaixo, envie com git push, que termina com main -> main. No site do GitHub, o equivalente é abrir um Pull request de develop para main e clicar em Merge pull request.
Duas formas de se proteger:
- Conferir antes de enviar. Depois de cada merge em
main, abra o.cpanel.ymle veja se oDEPLOYPATHaponta parapublic_html. Leva dez segundos. - Nunca editar o
.cpanel.ymlno branch de teste junto com outras mudanças. Commit separado, só com esse arquivo, facilita desfazer a parte errada de um merge.
Trocar de branch sem perder o que foi editado no servidor
A interface do cPanel não deixa trocar o branch em checkout, nem publicar, quando o repositório tem alterações não commitadas. É uma proteção: o painel prefere recusar a apagar seu trabalho. Para seguir, você decide o que fazer com essas alterações.
Existem dois lugares onde alguém costuma "editar direto no servidor", e eles se comportam de forma diferente.
Quando a edição foi feita na pasta publicada
Se você (ou um plugin, ou o editor de temas do WordPress) alterou um arquivo dentro de public_html, o repositório não vê essa mudança, porque a pasta publicada não é o repositório. O painel não vai reclamar, e o próximo deploy copia a versão do Git por cima e a edição some.
Antes de publicar de novo, baixe pelo Gerenciador de Arquivos o arquivo que foi alterado, leve a alteração para o seu repositório local, faça commit e push. Só então use Update from Remote e Deploy HEAD Commit.
Quando a edição foi feita dentro da pasta do repositório
Aqui o cPanel vai bloquear a troca de branch. Abra Terminal no cPanel (em Avançado, se estiver liberado no seu plano) e rode, um comando por vez:
cd ~/repositorios/site-teste
git status
A primeira linha entra na pasta do repositório. A segunda lista os arquivos alterados em vermelho, em Changes not staged for commit, e os arquivos novos em Untracked files. Se não aparecer nada, não há o que guardar.
Para guardar as alterações sem perdê-las:
git stash push -u -m "edicao feita no servidor"
git status
O stash tira as alterações da pasta e as guarda num espaço à parte; o -u inclui arquivos novos. O segundo git status deve responder nothing to commit, working tree clean. Agora o painel aceita trocar de branch.
Para ver e recuperar depois:
git stash list
git stash pop
O list mostra as alterações guardadas com a mensagem que você deu. O pop devolve a mais recente para a pasta. Se ela conflitar com o branch atual, o Git avisa com CONFLICT e mantém a alteração guardada no stash (ela continua aparecendo em git stash list). Para desfazer a tentativa, rode git checkout HEAD -- .: ele volta os arquivos rastreados para a versão do último commit, inclusive os que ficaram em conflito. Arquivos novos que o -u trouxe de volta continuam na pasta. O git status lista esses arquivos em Untracked files. Apague-os pelo Gerenciador de Arquivos ou com git clean -fd, que remove de vez todo arquivo não rastreado da pasta do repositório. Antes, rode git clean -nd para ver a lista do que seria apagado. Depois use git stash show -p para ver as linhas alteradas na tela.
Atenção: depois do pop, a pasta volta a ter alterações não commitadas, e o painel volta a bloquear troca de branch e deploy até o repositório ficar limpo. Por isso, decida o destino da alteração:
- Deve ir ao ar: reproduza a mudança no repositório do seu computador, no branch certo, e faça commit e push. Depois limpe a cópia do servidor com
git stash push -useguido degit stash drop, use Update from Remote e Deploy HEAD Commit. - Não deve ir ao ar: descarte com
git stash push -useguido degit stash drop. Odropapaga a alteração guardada de vez, então só rode depois de ter certeza.
Nos dois casos, git status deve terminar respondendo nothing to commit, working tree clean.
O caminho mais limpo continua sendo não editar no servidor. Toda mudança que nasce no seu computador e passa por commit chega aos dois ambientes do mesmo jeito.
Erros comuns e como sair deles
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Painel não deixa trocar de branch | Alterações não commitadas na pasta do repositório | git status e git stash push -u, como na seção anterior |
| Deploy não roda ou fica desabilitado | Falta .cpanel.yml na raiz do branch, ou o repositório não está limpo |
Confira o arquivo no branch em checkout e rode git status |
| Mudança apareceu no teste mas não em produção | .cpanel.yml do teste veio no merge para main |
Corrija o DEPLOYPATH em main, commit, push, Update e Deploy |
| Edição feita no site sumiu após publicar | Arquivo foi alterado na pasta publicada, fora do Git | Restaure do backup e leve a mudança para o repositório |
| Update from Remote falha com erro de permissão | Chave SSH do servidor não autorizada no remoto privado | Gere a chave em Acesso SSH > Gerenciar chaves SSH, cole a pública nas Deploy keys do GitHub ou GitLab e use a Clone URL git@..., como no Passo 1 |
O guia de troubleshooting do cPanel tem outras situações, incluindo deploy por push direto para o servidor, que dispensa o botão Update.
Quando essa montagem não compensa
Se o seu site é WordPress e o que muda entre teste e produção é conteúdo, plugin instalado pelo painel ou configuração, dois branches no Git resolvem pouco. Nada disso está em arquivo versionado. Nesse cenário, o staging do WordPress Toolkit (quando disponível no seu cPanel) clona arquivos e banco juntos e tem uma função de sincronização, o que atende melhor e dá menos trabalho.
A montagem com dois branches vale a pena quando o que você desenvolve é código: um tema próprio, um plugin feito por você, um site em PHP ou HTML sem CMS. Aí o Git dá histórico, permite voltar a um commit anterior e garante que o teste e a produção recebem exatamente os mesmos arquivos, só que em momentos diferentes.
Um último cuidado: o subdomínio de teste é público. Se ele não deve aparecer no Google, proteja a pasta com senha em Privacidade de Diretório no cPanel. Isso evita conteúdo duplicado e visitante caindo numa versão inacabada do site.
Referências
- Documentação oficial (cpanel) — Guide to Git - Advanced Configuration and Troubleshooting. Consultado em 2026-11-14.