blog
Painéis

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.

JR · · 12 min de leitura · 2 tabelas · 9 blocos de código

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
  1. Como a montagem funciona
  2. Antes de começar: backup e o subdomínio de teste
  3. Criando os dois repositórios no cPanel
  4. Por que cada branch precisa de um .cpanel.yml diferente
  5. Trocar de branch sem perder o que foi editado no servidor
  6. Erros comuns e como sair deles
  7. Quando essa montagem não compensa

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.

  1. No cPanel, abra Gerenciador de Arquivos, selecione a pasta public_html, clique com o botão direito e escolha Compress (Compactar). Baixe o .zip gerado para o seu computador.
  2. 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.
  3. 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 .zip gerado contém a própria pasta public_html, então ele deve ser enviado e extraído em /home/usuario (a pasta acima), nunca dentro de public_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 de public_html e só então extraia o .zip em /home/usuario. Depois de extrair, abra public_html e confira que não surgiu uma pasta public_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:

  1. 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.
  2. Na lista Chaves públicas, clique em Exibir/Baixar na chave criada e copie o texto inteiro.
  3. No GitHub, abra o repositório, Settings > Deploy keys > Add deploy key e cole. No GitLab, Settings > Repository > Deploy keys.
  4. 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 URL https:// 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:

Caminho do código até o arCommit em developCom o .cpanel.yml de testeDeploy do testeConferir o subdomínioMerge para mainConferir o DEPLOYPATHDeploy de produçãoDestino public_html
Ordem de publicação: o teste sai primeiro e o .cpanel.yml de produção é conferido antes do 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:

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.

O que fazer com a edição no servidorPainel bloqueia a troca de branchHá alterações não commitadasRode git stash push -uRepositório fica limpoDeve ir ao ar?Sim: reproduza no computador, commit e pushNão deve ir ao ar?Não: git stash drop para descartar
Decisão sobre a edição feita dentro da pasta do repositório no servidor.

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

  1. Documentação oficial (cpanel) — Guide to Git - Advanced Configuration and Troubleshooting. Consultado em 2026-11-14.
Leia também