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

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

João Rizzon · 2026-11-16 · Painéis

---

## 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](https://docs.cpanel.net/knowledge-base/web-services/guide-to-git-advanced-configuration-and-troubleshooting/).

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 `.zip` gerado 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 `.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:

- 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, `git@github.com: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:

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

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

```bash
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](https://docs.cpanel.net/knowledge-base/web-services/guide-to-git-advanced-configuration-and-troubleshooting/); aqui interessa só o destino. Exemplo para o branch `develop`, publicando um tema:

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

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

```bash
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.yml` e veja se o `DEPLOYPATH` aponta para `public_html`. Leva dez segundos.
- **Nunca editar o `.cpanel.yml` no 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:

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

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

```bash
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 -u` seguido de `git stash drop`, use **Update from Remote** e **Deploy HEAD Commit**.
- **Não deve ir ao ar:** descarte com `git stash push -u` seguido de `git stash drop`. O `drop` apaga 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](https://docs.cpanel.net/knowledge-base/web-services/guide-to-git-advanced-configuration-and-troubleshooting/) 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.

