Implementação automática a partir do GitHub, GitLab ou Bitbucket com rollback instantâneo

O sistema de implementação automática liga os seus repositórios do GitHub, GitLab, Bitbucket, Gitea/Forgejo ou de qualquer servidor Git acessível por HTTPS ao seu alojamento, preparando uma versão nova do código antes de a ativar através de uma ligação simbólica. Pode voltar rapidamente a uma versão guardada. A continuidade da aplicação depende também das suas migrações, ficheiros partilhados e scripts; a mudança de código não reverte esses dados.

Se o seu repositório contiver React, Vue ou outro frontend que resulte em ficheiros HTML, CSS e JavaScript, consulte também como alojar um site estático ligado a uma API externa.

Aceda à ferramenta na área de cliente, em Alojamento → selecione o seu serviço → Deploy+.

Ligar um repositório

Clique em Ligar repositório. O registo faz-se em três passos dentro do mesmo cartão; enquanto um passo não estiver resolvido, não é possível passar ao seguinte, por isso os erros aparecem onde se corrigem.

Passo 1 · Repositório

• Fornecedor: GitHub, GitLab, Bitbucket, Gitea/Forgejo ou «Outro servidor Git». O GitLab e o Gitea admitem instalações próprias: basta que o URL aponte para o seu servidor.
• URL do repositório: o endereço https:// do repositório, o mesmo que usaria para o clonar. Os URLs SSH (git@servidor:cuenta/repo.git) não servem: a implementação clona por HTTPS com token.
• Token de acesso: é guardado cifrado e utilizado para aceder ao repositório e, quando for o caso, consultar a API do fornecedor e gerir o webhook. Para um repositório público, pode deixá-lo vazio. O menu «Como criar o token» indica, para o fornecedor escolhido, onde criá-lo e que permissões exatas precisa.
• Verificar acesso: consulta a API do fornecedor e responde com o repositório, se é público ou privado, o ramo predefinido e a lista de ramos. Se faltar uma permissão ao token, é aqui que o diz, e não a meio da primeira implementação.
• Ramo que é implementado: escolhe-se no menu com os ramos lidos do repositório.

Permissões que cada fornecedor pede:

Com Outro servidor Git não há API para consultar: o acesso não é verificado, os ramos não são lidos e o webhook não pode ser criado automaticamente. A implementação em cada push faz-se chamando o URL manual a partir da sua própria integração. Ser-lhe-á pedido também o utilizador com que o seu servidor aceita a autenticação HTTPS (consulte o utilizador exigido pelo seu fornecedor).

Crie sempre o token com a validade mais curta que lhe sirva, revogue-o quando eliminar a implementação e renove-o antes de expirar, sem lhe alargar as permissões. No GitHub, não utilize um token classic com o âmbito global repo.

Passo 2 · Destino e projeto

• Tipo de projeto: escolha Laravel, Symfony, WordPress, PHP/Composer, Frontend compilado, HTML estático ou Outro projeto. O perfil propõe uma raiz web, os ficheiros partilhados e um script adequados, que pode rever antes de guardar.
• Nome do repositório: um identificador para o reconhecer na lista; é preenchido automaticamente com o nome do repositório.
• Pasta onde é publicado: public_html para o domínio principal, subdominios/app para um subdomínio. Por baixo do campo vê-se o caminho final completo e o que essa pasta serve.
• Raiz web dentro do repositório: o perfil configura-a como public para Laravel e Symfony, dist para um frontend compilado ou a raiz para os projetos que não usam uma subpasta pública. Altere-a se o seu build gerar outro diretório, como build ou out.
• Ficheiros e pastas partilhados: um caminho por linha; são guardados fora de cada versão e ligados em todas.
• Versões que são guardadas: quantas releases anteriores se mantêm para voltar atrás. Por predefinição, 5.

Passo 3 · Automatização

• Implementar ao fazer push: se o fornecedor tiver API e o token puder gerir webhooks, criamo-lo nós ao ligar o repositório. Caso contrário, a ficha dá-lhe o URL (e o segredo, se pedir assinatura) para os colar na configuração de webhooks do fornecedor.
• Verificar a assinatura de cada aviso: só são aceites os avisos assinados pelo fornecedor. O GitHub e o Bitbucket assinam com HMAC-SHA256, o Gitea também, e o GitLab envia o segredo no cabeçalho X-Gitlab-Token.
• Agendar o scheduler do Laravel: num projeto Laravel vem assinalado. Quando a primeira implementação termina com êxito, acrescentamos às suas tarefas cron php artisan schedule:run a cada minuto no current da aplicação, com o caminho absoluto do PHP escolhido na sua conta. Explicamo-lo em O scheduler do Laravel.
• Script de implementação: reveja o que o perfil propõe ou escolha Apenas compilar assets com Node, PHP com Composer ou Sem script. Também pode escrever os seus próprios comandos; é guardado o que ficar na caixa de texto.

O passo termina com um resumo do que escolheu e o botão Ligar repositório.

Executar a implementação

Ao clicar em Ligar repositório, o sistema verifica o acesso SSH (ativando-o automaticamente se for necessário), valida a configuração e guarda o repositório. Este aparece então na lista com um botão Implementar agora.

Clique em Implementar agora para a primeira implementação. O caminho tem de estar vazio: se contiver um site anterior, o sistema pedir-lhe-á que faça uma cópia e retire esse conteúdo antes de continuar.

Durante a implementação, o cartão de progresso mostra os passos uns por baixo dos outros (ligação, clonagem, ficheiros partilhados, script, ativação e limpeza), com o tempo que cada um demorou e o total. A consola fica recolhida atrás de Ver consola: se algo falhar, o passo com erro abre-se sozinho com as últimas linhas da saída, uma explicação do que aconteceu e os botões para tentar novamente ou corrigir o token ou o URL. Se o erro ocorrer antes de ativar o código novo, continua publicada a versão anterior. Reveja o passo que falhou: os scripts podem ter alterado dados partilhados, e um erro posterior à ativação exige verificar que versão está o site a servir.

O detalhe do repositório mostra também um URL de implementação manual para integrações externas. Esse URL contém um segredo capaz de iniciar implementações: não o publique, não o inclua em capturas de ecrã nem em registos e regenere-o de imediato se ficar exposto.

Scripts personalizados

A maioria dos projetos precisa de executar comandos durante a implementação para instalar dependências ou compilar assets. Aceda ao editor clicando no menu do repositório (três pontos) → Editar script.

Como o script é executado

O editor oferece dois modos, e pode passar de um para o outro quando quiser sem que o texto do script mude:

• Um comando por linha: o modo de sempre, e o que mantêm todos os repositórios ligados antes de a opção existir. Cada linha é executada em separado, na sua própria shell e a partir da pasta da versão nova, por isso um cd ou um export não chegam à linha seguinte. Se um comando falhar, os seguintes não são executados.
• Script Bash completo: o script inteiro corre numa única shell Bash, de cima para baixo, com condicionais, ciclos, funções e variáveis que se mantêm de uma linha para outra. Para no primeiro comando que falha, como com set -e, e o registo indica qual foi, tal como está escrito. Uma falha a meio de um pipe (comando | outro) não o interrompe, salvo se começar o script com set -o pipefail. Ao guardar, o editor verifica que o Bash entende o script.

No modo Bash, o NVM é carregado uma vez e serve para o resto do script:

composer install --no-dev --optimize-autoloader --no-interaction

if [[ "$HOSTSUAR_DEPLOY_TRIGGER" == "webhook" ]]; then
    php artisan migrate --force
fi

export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"
npm ci --include=dev
npm run build

Um exit 0 termina o script antes do tempo sem dar a implementação como falhada. Um comando que espere uma resposta pelo teclado não a recebe: acrescente a opção que o torna não interativo, como --no-interaction no Composer.

Variáveis para o script

Por baixo do script há dois interruptores independentes. Funcionam nos dois modos.

Dados da implementação disponibiliza ao script estas variáveis. Vem ativado nos repositórios ligados a partir de 23 de setembro de 2026; nos anteriores está desligado até o ativar.

Nenhuma contém segredos: não incluem o token do Git nem o segredo do webhook. Um rollback que tenha de reconstruir uma versão eliminada executa o script com HOSTSUAR_DEPLOY_TRIGGER=rollback e o commit dessa versão.

Variáveis do .env passa as chaves do .env partilhado ao script e a tudo o que este lançar, como um bash scripts/deploy.sh, o Composer, o npm ou o Artisan. O ficheiro não é alterado e as variáveis só existem enquanto dura a implementação:

• São lidas com o vlucas/phpdotenv, o mesmo leitor que o Laravel usa, com as suas regras de aspas, comentários e interpolação ${VARIABLE}. Se o Laravel não aceitar o ficheiro, a implementação para antes do script e o registo explica-o sem mostrar o seu conteúdo.
• Uma chave que já existe no ambiente da conta, como PATH ou HOME, mantém o seu valor, tal como no Laravel.
• Não são passadas as chaves que o Bash não admite como variável (com ponto ou hífen, ou nomes próprios da shell como IFS ou UID) nem as que começam por HOSTSUAR_DEPLOY_. O registo indica quais ficaram de fora.
• Os valores viajam num ficheiro temporário que só a sua conta pode ler e que é apagado no fim, também se a implementação falhar. Nunca aparecem na linha de comandos. Se o processo for interrompido abruptamente a meio, o ficheiro é apagado numa implementação posterior com esta opção ativada, passadas duas horas.
• Se não houver .env, o script corre sem estas variáveis e o registo indica-o.

Tenha em conta dois efeitos antes de o ativar:

• O que o script imprime fica guardado no histórico. O Deploy+ oculta os valores cujas chaves parecem secretas (contêm PASSWORD, SECRET, TOKEN ou KEY, entre outras) e os endereços com utilizador e palavra-passe, como mysql://usuario:clave@host, mas não consegue reconhecê-los todos, e os valores com menos de 8 caracteres não são ocultados. Não imprima segredos nem ative set -x, que mostra cada comando com os seus valores.
• O framework também vê as variáveis. No Laravel, se APP_ENV chegar como variável (do .env ou da sua própria conta) e o repositório incluir um .env.production (ou o ficheiro que corresponda ao seu valor), enquanto o script corre o Laravel lê esse ficheiro em vez do .env, também em php artisan config:cache. Mas não substitui as chaves que já chegam como variáveis: se o .env disser APP_DEBUG=true e o .env.production disser APP_DEBUG=false, fica com true. O registo avisa quando deteta esse ficheiro. No Symfony, as variáveis do sistema têm prioridade sobre .env.local e .env.prod.local: se usar esses ficheiros para sobrepor o .env, deixe esta opção desligada.

Exemplos

Exemplos para projetos que incluem os seus ficheiros de bloqueio (composer.lock ou package-lock.json) e os scripts de compilação indicados. npm ci --include=dev instala também as ferramentas de construção; exige que o ficheiro de bloqueio esteja sincronizado. Verifique antes as versões de PHP e Node de que o projeto precisa:

Laravel com Composer e npm:

composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm run build

Não acrescente php artisan queue:restart: o script corre antes de ativar a versão, e o Deploy+ já reinicia os seus workers depois. Explicamo-lo em Workers de filas e processos persistentes.

WordPress com npm:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm run build

Projeto PHP simples:

composer install --no-dev

Os scripts são executados na nova versão antes de a ativar, pelo que uma falha do script impede a ativação desse código novo. Ainda assim, as suas operações sobre uma base de dados, serviços externos ou caminhos partilhados podem afetar o site publicado e não são desfeitas automaticamente. O editor não guarda um script que use comandos bloqueados como sudo, chmod 777, dd, mkfs, fdisk, shutdown, reboot ou halt: indica a linha para que a retire. Admite pkill e kill, que só afetam os processos da sua conta. Para reiniciar os workers de filas não precisa deles: php artisan queue:restart faz com que terminem ordenadamente o trabalho em curso antes de sair. Até 23 de setembro de 2026, essas linhas eram eliminadas ao guardar sem aviso, e também outras que apenas continham essas letras dentro de uma palavra, como git add. Se guardou o seu script antes dessa data, abra-o e verifique que mantém todas as linhas previstas.

O Deploy+ verifica o Node.js antes de executar estes comandos e instala-o automaticamente se faltar. Se o projeto exigir uma versão concreta, selecione-a antes no Gestor de pacotes.

Ficheiros partilhados e .env

O ficheiro .env é preservado automaticamente entre implementações. Para partilhar ficheiros ou pastas adicionais, aceda a Ficheiros partilhados (menu → Ficheiros partilhados) e indique os caminhos relativos, um por linha.

Por exemplo:

storage/app
storage/logs
uploads

Os ficheiros partilhados são guardados em ~/deploy/nombre-repo/shared/ e ligados automaticamente em cada versão. Pode editar o .env diretamente a partir do menu → Editar .env. O ficheiro partilhado é atualizado de imediato e, nas aplicações Laravel, as caches são limpas automaticamente. Num frontend compilado, as variáveis que são incorporadas no JavaScript só mudam ao executar um build novo, pelo que depois tem de lançar outra implementação.

A opção de variáveis de ambiente do Deploy+ gere esse ficheiro .env; não é um armazém global de variáveis do servidor nem exporta automaticamente os seus valores para todos os processos. Cada aplicação tem de carregar o ficheiro com o mecanismo do seu framework ou com uma biblioteca equivalente. O Laravel, por exemplo, utiliza o vlucas/phpdotenv. Um PHP web ou uma tarefa cron conseguirá ler os valores se iniciar a aplicação ou o seu carregador de configuração; um comando independente que não carregue o .env não os receberá como variáveis do sistema. A exceção é o script de implementação: com o interruptor Variáveis do .env ativado, os seus comandos recebem os valores como variáveis (consulte a secção Variáveis para o script).

O LiteSpeed e o PHP Selector não oferecem, dentro da conta, um gestor de segredos partilhado entre o PHP web, o cron e o Deploy+. As variáveis que o administrador do servidor possa fornecer ao PHP web não passam por isso para os outros dois contextos. O Deploy+ também não inclui atualmente uma integração com gestores externos como o 1Password: se a aplicação utilizar um, é ela que tem de implementar a consulta e entregar os valores a cada processo.

As variáveis são carregadas dentro de cada processo e não passam sozinhas para outras aplicações. No entanto, todas as aplicações de uma mesma conta cPanel são executadas com o mesmo utilizador: um processo dessa conta poderia ler o .env se conhecesse a sua localização. Guardá-lo fora da raiz web impede que seja descarregado por HTTP, mas não cria uma fronteira de segurança entre as aplicações da conta. Para um isolamento completo, é necessário um serviço de alojamento independente, com outro utilizador de sistema.

Para verificar os três contextos, pode utilizar primeiro uma variável sem informação secreta. O teste deve fazer com que o PHP web, o cron e o comando de implementação iniciem o mesmo carregador; não é preciso alterar credenciais reais nem reiniciar o servidor. Se um contexto não carregar o ficheiro, a ausência da variável descreve esse processo, não uma perda do .env partilhado.

Prepare o conteúdo persistente antes de o publicar. Um caminho partilhado existente prevalece sobre o ficheiro que chegue no repositório; acrescentá-lo à lista não combina automaticamente as duas versões. Não inclua numa pasta partilhada código que queira atualizar em cada implementação. Evite partilhar node_modules se utilizar npm ci: esse comando elimina e reconstrói a pasta, e poderia afetar outras releases que apontassem para ela. Guarde uma cópia antes de alterar esta configuração.

O .env partilhado afeta a aplicação ativa. Numa instalação Laravel existente, mantenha a sua APP_KEY; alterá-la não faz parte de uma implementação habitual. Não introduza segredos nas variáveis que um frontend compila dentro do JavaScript público. Antes de editar o .env, guarde uma cópia privada: o rollback muda o código publicado, mas não recupera uma versão anterior deste ficheiro.

Histórico e rollback

O Histórico de implementações abre-se a partir do menu do repositório e aparece dentro da respetiva ficha, numa tabela com data, origem (Manual, Push, Rollback ou Agendado), commit implementado com a sua mensagem e autor, duração e estado. O filtro Todos / Falhados permite ver apenas o que falhou. Clique em Ver detalhe para expandir os passos com os seus tempos e a saída completa da consola.

Para fazer rollback para uma versão anterior, localize a implementação no histórico e escolha Voltar a esta versão no seu menu; é pedida confirmação antes de alterar o que quer que seja. O sistema verifica que a versão existe, muda a ligação simbólica para apontar para ela e atualiza o diretório. Quando a release continua disponível, não precisa de clonar o código novamente e a mudança costuma ser rápida. Verifique depois que as páginas e operações principais funcionam com os dados atuais.

Se a versão já não estiver no servidor porque a limpeza automática a apagou, o sistema reconstrói-a: clona o repositório e pede ao seu fornecedor Git esse commit concreto. Demora mais do que um rollback normal e exige que o fornecedor permita recuperar o commit e que as credenciais continuem válidas. Também volta a executar o script configurado, que tem de continuar a ser compatível com esse código e as suas dependências.

Voltar a uma versão que continua no servidor não executa o script. Os processos persistentes da aplicação passam, esses sim, para a versão restaurada: o Deploy+ reinicia-os no fim, tal como após uma implementação, e o registo desse regresso indica como ficou cada um.

O rollback não restaura a base de dados, o .env nem os ficheiros partilhados. Planeie em separado a recuperação de uma migração ou de dados alterados. As versões guardadas não substituem uma cópia de segurança.

Se uma implementação estiver em curso e precisar de a cancelar, clique em Cancelar deploy. Aguarde que o estado confirme o cancelamento e reveja o site. O pedido pode chegar quando uma operação já está em curso; cancelar não reverte as suas alterações nos dados nem substitui um rollback depois da ativação.

O scheduler do Laravel

As tarefas que o Laravel programa em routes/console.php só são executadas se algo lançar php artisan schedule:run a cada minuto. Ao ligar um projeto Laravel, Agendar o scheduler do Laravel vem assinalado: quando a primeira implementação termina com êxito, acrescentamos esta tarefa ao seu cron, e o registo dessa implementação confirma-o.

* * * * * /opt/alt/php84/usr/bin/php /home/tu_usuario/deploy/nombre-repo/current/artisan schedule:run >/dev/null 2>&1 # hostsuar-deploy-12

Leva a versão de PHP escolhida na sua conta no momento em que é programada, e o número no fim identifica o repositório. Como entra por current, cada execução usa a versão publicada nesse momento: não é preciso alterá-la em cada implementação. É uma tarefa sua como qualquer outra: vê-a em cPanel > Cron Jobs e pode alterá-la ou apagá-la. Se mudar depois a versão de PHP da conta, a tarefa continua com a sua: altere-a também aí.

Se o seu cron já tiver uma tarefa com schedule:run, por exemplo a da instalação anterior, não acrescentamos outra: com duas, cada tarefa programada seria executada duas vezes. O registo da implementação indica qual encontrou e que comando colocar. Se era a da instalação anterior, altere-a para apontar para o current do Deploy+. As de outras aplicações publicadas com o Deploy+ na mesma conta não contam.

Se eliminar a configuração do repositório, a tarefa fica, tal como o site publicado.

Workers de filas e processos persistentes

Nos planos Avanza, Max e Elastic, um worker de filas, o Horizon ou um comando próprio podem ficar em execução como processos persistentes, em Ferramentas > Processos. Para uma aplicação publicada com o Deploy+, a pasta do processo é deploy/nombre-repo/current: em cada arranque entra em current, que aponta sempre para a versão ativa.

Um worker carrega o código ao arrancar e não o volta a ler. Por isso, assim que termina cada implementação, o Deploy+ reinicia os processos persistentes que trabalham nessa aplicação, os que têm como pasta o seu current ou uma pasta dentro dele. Também o faz ao voltar a uma versão anterior a partir do histórico. Cada worker termina o trabalho que tiver em mãos e volta a arrancar num segundo com o código publicado.

O registo da implementação indica-o com uma linha por processo, por exemplo «Reiniciado «Worker de pedidos»: em curso com a versão nova». Se algum não tiver podido ser reiniciado, a linha indica-o e a implementação continua a contar como concluída, porque a versão já está publicada: reinicie-o em Ferramentas > Processos.

Se a aplicação tiver processos, a sua ficha no Deploy+ mostra-os no bloco Processos desta aplicação, com o seu estado e o que executam. Num projeto Laravel sem worker, o menu do repositório (a seta junto a Implementar agora) tem Adicionar worker de filas, que abre o registo em Processos com a pasta da aplicação e a versão de PHP da sua conta já preenchidas. Ao ligar um projeto Laravel novo, pode assinalar Manter um worker de filas em funcionamento: é criado quando a primeira implementação termina com êxito, com a fila default, e o registo dessa implementação confirma-o ou explica porque não pôde ser criado, por exemplo se não restarem processos livres no plano.

Não é preciso php artisan queue:restart nem horizon:terminate no script: o script corre na versão nova antes de a ativar, por isso um reinício a partir daí voltaria a arrancar o worker sobre a versão anterior.

Se não tiver processos persistentes e processar a fila a partir do scheduler, cada execução arranca com o código publicado nesse momento e não é preciso reiniciar nada.

Versão de PHP

A versão de PHP de um site publicado com o Deploy+ não se altera na secção PHP da área de cliente, porque cada implementação substitui a pasta publicada. Fixe-a no .htaccess da raiz web do seu repositório ou use a versão predefinida da conta. Explicamo-lo em Versão de PHP num site publicado com o Deploy+.

Como funciona a ferramenta de implementação

O sistema cria uma estrutura em ~/deploy/nombre-repo/ com três diretórios principais: releases/ contém cada versão implementada com timestamp, current é uma ligação simbólica para a versão ativa e shared/ contém ficheiros partilhados como o .env e storage/. O seu diretório web (public_html ou outro) aponta para current, que por sua vez aponta para a versão ativa em releases/.

Quando executa uma implementação, é criada uma nova pasta em releases/, o código é clonado, os scripts são executados e, quando tudo está pronto, current é atualizado para apontar para a nova versão. A mudança da ligação é rápida, mas não garante por si só que todos os pedidos, processos ou alterações de esquema sejam compatíveis durante a publicação. O rollback funciona da mesma forma: simplesmente muda current para uma versão anterior que já existe.

A clonagem é feita com profundidade 1: cada versão recebe os ficheiros do último commit do ramo, não o histórico do repositório. Num repositório com anos de vida, o histórico pesa muito mais do que o próprio código, por isso a implementação é bastante mais rápida e cada versão ocupa menos espaço na sua conta. Se o seu script de implementação precisar do histórico (por exemplo git describe ou git rev-list --count para gerar um número de versão), não o encontrará. Se lhe bastar identificar o commit, use $HOSTSUAR_DEPLOY_COMMIT ou $HOSTSUAR_DEPLOY_COMMIT_SHORT; se precisar de um número de versão, guarde-o num ficheiro a partir do seu sistema de integração contínua ou calcule-o de outra forma.

Resolução de problemas

A conta não tem acesso SSH: a ferramenta tenta ativá-lo automaticamente. Se o servidor rejeitar a chave mesmo depois de a reinstalar, volte a executar a implementação e contacte o suporte com o registo; a ferramenta usa uma chave gerida e não depende da palavra-passe do cPanel. Já existe uma implementação em curso: só pode haver uma implementação ativa por repositório; aguarde que termine ou cancele-a. Os scripts personalizados falham: consulte o registo da implementação para identificar que comando falhou; no modo Bash, a última linha indica o comando exato em que parou. Se um script escrito para Bash falhar no modo de um comando por linha (um cd ou um export que não chega à seguinte, um if repartido por várias linhas), mude o modo para Script Bash completo. Uma falha anterior à ativação impede a publicação do código novo; verifique também possíveis alterações em dados partilhados. O webhook não é acionado: verifique na configuração de webhooks do fornecedor (no GitHub, Settings → Webhooks) que está criado e reveja as entregas recentes. Se a ficha do repositório indicar «Webhook pendente», use Instalar; se indicar «Webhook manual», copie o URL que aparece no detalhe e cole-o no fornecedor. O fornecedor rejeita o token ao clonar: cada marca di-lo de uma forma («HTTP Basic: Access denied» no GitLab, um 403 no GitHub, «Invalid or expired token» no Bitbucket). O registo da implementação traduz essas mensagens e indica que permissão falta ou se o token expirou.