Deploys e Rollback

Um deploy é o processo que leva o código do seu repositório Git até o site em produção no servidor. No PrimeForge cada deploy passa por um pipeline estruturado, com o log transmitido em tempo real, releases atômicas e rollback em um clique. Esta página explica a página Deployments de um site, como disparar deploys (manuais e automáticos), como ler o log ao vivo e como voltar para uma versão anterior quando algo dá errado.

Você encontra a página Deployments na sub-navegação de qualquer site, logo abaixo de Visão geral e ao lado de Ambiente e Domínios e SSL.

Aba Deployments com o histórico de deploys do site

A página Deployments

A página Deployments abre pelo histórico, que é o que você consulta na maior parte das vezes:

  • Histórico de deploys — a lista de todos os deploys já executados, do mais recente para o mais antigo, com o status de cada um (Concluído, Falhou, Em execução, Pendente, Ignorado ou Cancelado), a origem (manual, deploy automático, API, rollback…), a release, o commit e a mensagem, quanto tempo levou e quando começou. A tabela se atualiza sozinha a cada 5 segundos, e um botão Ocultar falhas pré-troca esconde os deploys que falharam antes de chegar ao ar.
  • Log ao vivo — o painel Deploy em andamento aparece no topo enquanto há um deploy rodando e some quando ele termina; um deploy já encerrado se abre pela sua própria linha no histórico.
  • Configurações e script de deploy — uma seção recolhida no rodapé com o deploy automático e a URL do webhook, quantas releases manter, o caminho do health check, os caminhos compartilhados e o editor do script de deploy (deploy.sh e os dois hooks).

Cada linha do histórico traz Ver log, que abre o log completo daquele deploy — útil para investigar uma falha antiga ou conferir exatamente o que rodou em uma versão específica. Conforme o estado, a linha também oferece Cancelar (deploy em andamento), Tentar novamente (deploy que falhou) e Ativar este release (uma release antiga que ainda está no servidor).

Disparar um deploy manual

Clique em Deploy, no cabeçalho de qualquer página do site. Ele age na hora, sem perguntar "tem certeza?": o deploy entra na fila imediatamente e um aviso aparece oferecendo Cancelar e um link para acompanhar a execução. O próprio botão vira o indicador de progresso enquanto o deploy roda ("Fazendo deploy…") — e diz "Deploy automático…" quando quem disparou foi um push, a API ou um rollback, em vez de um clique seu.

A confirmação continua existindo onde um clique errado é mais fácil: no menu de cada linha da lista de sites (Fazer deploy agora, que pergunta "Fazer deploy de {domínio} a partir da branch {branch}?") e na paleta de comandos.

Confirmação "Fazer deploy do site", aberta a partir da lista de sites

O deploy manual está sempre disponível, mesmo com o deploy automático via Git ligado — um não substitui o outro. É comum manter o deploy automático na branch main e disparar deploys manuais de branches de teste quando necessário.

Um deploy também pode ser disparado pela API, enviando uma requisição POST autenticada com a sua chave de API. Isso é útil para integrar o PrimeForge a uma pipeline de CI própria.

O pipeline de 6 estágios

Todo deploy segue uma sequência ordenada de etapas. Enquanto ele roda, o log ao vivo da página Deployments mostra uma barra de progresso com seis segmentos que acendem um a um, com um cursor piscando no estágio ativo:

Fetch → Infra → Script → Restart → Health → Live

Cada estágio tem uma responsabilidade clara. Entender o que cada um faz ajuda a interpretar onde um deploy falhou e por quê.

Fetch — busca o código

Clona ou atualiza o repositório Git. No primeiro deploy o repositório é clonado por inteiro; nos deploys seguintes o PrimeForge busca as novidades e faz reset para o commit mais recente da branch configurada. É também aqui que o painel lê o .env.example do seu repositório e completa automaticamente qualquer variável que esteja faltando no .env do site — segredos que já existem nunca são sobrescritos. Por isso um app Laravel recém-criado costuma subir corretamente sem que você precise editar o .env na mão.

Infra — prepara a infraestrutura no host

Garante que a infraestrutura do site no host esteja pronta e alinhada às opções atuais do site (banco, Redis, Horizon, Reverb, etc.): o vhost do nginx, o pool do php-fpm (sites PHP/Laravel) ou a unit systemd do site (Node/Next.js) e o slice do systemd. Este estágio converge sem reiniciar à força a versão que já está servindo tráfego — ele nunca derruba o que está no ar. O restart de fato acontece só no estágio Restart, depois da troca.

Script — o seu script de deploy

Como no Laravel Forge, o script de deploy é o build: o painel não roda composer install, npm ci, npm run build nem comandos artisan por conta própria — eles ficam no deploy.sh do site, que você edita (veja O script de deploy e os hooks abaixo). Neste estágio o PrimeForge roda o hook pré-deploy e, logo depois, o deploy.sh, como o usuário Linux do site, dentro da nova release, com bash -e -o pipefail: o primeiro comando que falhar faz o deploy falhar, e a release atual continua no ar. A saída do script aparece no log do deploy.

Se você tem credenciais de pacotes privados cadastradas (Composer auth.json, NPM .npmrc), elas ficam disponíveis para o script durante a execução e são removidas logo depois.

Builds pesados (Vite, Tailwind, TypeScript) consomem bastante memória. Se um deploy falhar com "exit code 137" ou "Killed", foi falta de memória durante o script — o log do deploy mostra um botão "Aumentar memória para {N} e tentar novamente" que dobra o limite e reexecuta com um clique.

Restart — reinicia os processos do site

Reinicia os processos do site (o pool php-fpm ou a unit systemd do site) e recarrega o nginx para que passem a executar o novo código. Em sites atômicos, é aqui que o symlink current aponta para a nova release — a troca (swap) que efetivamente coloca a nova versão no ar.

Health — verifica a saúde

Envia uma requisição HTTP para o caminho de health check do site (por padrão /up). Se a resposta for 200 OK, o deploy é considerado bem-sucedido. Se o health check continuar falhando depois das tentativas, o deploy é marcado como Falhou — e, em sites atômicos, a versão anterior continua no ar sem que o visitante perceba.

Live — no ar

O deploy terminou com sucesso e a nova versão está servindo tráfego.

O log de deploy ao vivo

Enquanto o pipeline roda, cada linha de saída é transmitida em tempo real para o painel, com carimbo de horário e agrupada pelo estágio que a gerou. As linhas surgem animadas conforme chegam e o estágio ativo mostra um cursor verde piscando, então você acompanha exatamente onde o deploy está a cada segundo, sem precisar recarregar a página. Copiar Log leva a saída inteira para a área de transferência, e Auto-scroll pode ser desligado para você ler com calma.

Log de deploy transmitido ao vivo, estágio a estágio

Quando um deploy falha, o log daquele deploy mostra:

  • Estágio da falha — em qual etapa o deploy abortou ("Falhou em: Script", por exemplo).
  • Mensagem amigável — uma tradução do erro quando o PrimeForge reconhece a causa (falta de memória, falha de rede, timeout de health check, etc.).
  • Erro bruto — a saída real do shell, para quem quiser o detalhe técnico.
  • Botões de ação — Tentar Deploy Novamente (reexecuta como está) e, quando o painel identifica uma causa específica, um botão de correção em um clique (como o "Aumentar memória" no caso de falha por falta de memória). Um deploy travado no meio se encerra pelo Cancelar da sua linha no histórico.

Deploy automático via Git (push-to-deploy)

Cada site pode ouvir os pushes da sua branch e fazer deploy sozinho, sem que você clique em nada. O deploy automático já vem ligado para sites novos — o assistente de criação mostra isso como uma opção explícita no passo Revisão. Você liga/desliga na linha Deploy automático da seção Configurações e script de deploy da página Deployments; a mesma linha mostra a URL de webhook do site (mascarada) com os botões Copiar URL do webhook e Rotacionar segredo do webhook.

Seção Configurações e script de deploy aberta na página Deployments

Ao ligar o deploy automático em um repositório do GitHub com um provedor conectado, o PrimeForge registra o webhook de push no repositório automaticamente. Quando você faz um push:

  1. O GitHub envia o payload do push para o endpoint do PrimeForge.
  2. O painel valida a assinatura HMAC contra o segredo exclusivo daquele site.
  3. A branch do push é comparada com a branch configurada — pushes de outras branches são ignorados silenciosamente.
  4. Um deploy normal é disparado.
  5. Deduplicação de deploys — se vários pushes chegam em sequência rápida, só o último deploy roda; os intermediários são marcados como Ignorado no histórico. Isso evita desperdiçar recursos quando você envia vários commits seguidos.

Ao desligar, o PrimeForge remove o webhook no GitHub e atualiza o estado no painel — que é sempre a fonte da verdade, mesmo que a chamada ao GitHub falhe.

O script de deploy e os hooks

O editor fica no fim da seção Configurações e script de deploy, na página Deployments, e tem uma aba para cada um dos três arquivos:

Script Quando roda Se falhar
Hook Pré-Deploy (hooks/pre-deploy.sh) Logo antes do deploy.sh, dentro da nova release O deploy falha (antes da troca — o visitante nunca vê)
Script de Deploy (deploy.sh) No estágio Script, dentro da nova release O deploy falha (antes da troca — a release atual continua no ar)
Hook Pós-Deploy (hooks/post-deploy.sh) Depois que o health check passa (a release já está no ar) Registrado como aviso — nunca derruba um deploy que já subiu

Acima do script, o editor mostra o que o painel faz antes dele (clonar a release · ligar shared/ e .env · nginx, php-fpm e processos do site · hook pré-deploy) e depois dele (trocar o current para a nova release · recarregar o nginx e reiniciar os processos do site — workers, Horizon, daemons, Node · health check · hook pós-deploy). Por isso o script não precisa reiniciar filas nem o Horizon: ele roda antes de a release ir ao ar, e o painel reinicia tudo depois da troca.

Os três arquivos rodam como o usuário Linux dedicado do site, dentro da nova release, com bash -e -o pipefail imposto pelo painel, e persistem entre as releases. O script de deploy tem até 12 minutos e cada hook até 2 minutos; passou disso, o painel interrompe tudo o que ele iniciou e o deploy falha com "timed out". Por isso não levam shebang nem uma linha set -euo pipefail. Um hook vazio não faz nada.

Quando um comando falha, o motivo do deploy diz a linha e o comando — por exemplo, Deploy script failed at line 7 (exit 2): ls /x — e Ver saída completa mostra toda a saída do script na ordem em que foi escrita, mensagens de erro junto com o resto.

O script padrão

No primeiro deploy, se o site ainda não tem um deploy.sh no servidor, o PrimeForge grava um padrão a partir do repositório clonado:

  • composer install quando há composer.json (exceto em sites estáticos);
  • a instalação do Node com o gerenciador indicado pelo lockfile — npm ci (ou npm install sem lockfile), corepack pnpm install --frozen-lockfile ou corepack yarn install --frozen-lockfile; bun cai para o npm;
  • o build só quando o package.json tem um script build ou o site tem um comando de build (em sites Next.js, sempre);
  • em apps com artisan: storage:link, migrate --force e optimize.

Para um site Laravel típico, o resultado é:

$PF_PHP /usr/local/bin/composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
npm ci
npm run build
$PF_PHP artisan storage:link
$PF_PHP artisan migrate --force
$PF_PHP artisan optimize

Um site estático só com HTML recebe um script vazio. Antes do primeiro deploy, o editor mostra uma prévia para o tipo do site, com o aviso de que o script real é gravado no primeiro deploy; se você salvar antes, o painel usa a sua versão.

Se o deploy deve ou não migrar o banco é só a linha $PF_PHP artisan migrate --force: remova-a para rodar as migrações por fora — a partir daí a responsabilidade de migrar é sua.

O artisan optimize guarda em cache a configuração, as rotas, os eventos e as views da nova release, antes da troca. Quando você altera o .env pelo painel (página Ambiente, ligar Redis/Reverb, uma restauração), o cache de configuração é refeito na hora, então a mudança vale sem novo deploy.

Variáveis e Snippets

Os scripts recebem PF_PHP (o binário php da versão do site, por exemplo php8.5), PF_SITE_PATH, PF_RELEASE_PATH, PF_SHARED_PATH, PF_DOMAIN, PF_BRANCH e PF_SITE_USER — a lista fica sempre visível no editor. A versão do Node do site vem primeiro no PATH, então npm e node são os da versão do site. Chame o Composer como $PF_PHP /usr/local/bin/composer para que ele rode no PHP do site — um composer puro usa o PHP padrão do servidor.

A gaveta Snippets traz blocos prontos para Inserir ou Copiar: composer install (PHP do site), artisan optimize, artisan migrate --force, artisan storage:link, npm ci + build e pnpm install + build.

Deploys atômicos e rollback

Sites novos fazem deploy de forma atômica. Em vez de sobrescrever o código no lugar, cada deploy monta um diretório novo em releases/{id}/ e só aponta o symlink current para ele quando o script de deploy termina com sucesso.

O efeito prático é importante:

  • Falha antes da troca é invisível — se o deploy falha no Fetch, Infra ou Script, o current continua apontando para a release anterior. O visitante nunca percebe.
  • Estado compartilhado sobrevive — arquivos que precisam durar entre releases (o .env, o storage/ do Laravel, o bootstrap/cache/ e um eventual banco SQLite) ficam em um diretório shared/, então não são perdidos quando releases antigas são removidas.

Rollback em um clique

Quando uma falha passa pela troca e chega à produção, use Reverter. A ação fica no cabeçalho do site, ao lado de Deploy (e na paleta de comandos, como Reverter o último deploy). O modal mostra a release atual e a release de destino e lembra que o schema do banco é forward-only; ao confirmar com Reverter agora, o PrimeForge reaponta o current para a release anterior e leva você à página Deployments para acompanhar — a versão antiga volta ao ar em segundos, sem rebuild. Para voltar a uma release mais antiga específica, use Ativar este release na linha dela no histórico. Cada release guarda também a versão de runtime (PHP/Node) com que foi construída, então o rollback restaura o código e o runtime correspondente.

O rollback restaura o código, não os dados. As migrações de banco são somente para frente (forward-only): um rollback não desfaz o que uma migração já alterou no banco. Se a nova versão migrou o schema, planeje a volta considerando isso.

O banner âmbar de "schema-ahead"

Como as migrações são somente para frente, o PrimeForge conta a tabela de migrações antes e depois do script de deploy. Se um deploy avançou o schema do banco, o site é marcado como schema-ahead e passa a exibir um banner âmbar — um lembrete de que o banco está à frente do código que estaria no ar caso você fizesse rollback.

O banner some sozinho no próximo deploy bem-sucedido para frente. Um rollback deliberadamente mantém o banner aceso, justamente porque ele restaura o código mas não os dados — e você precisa estar ciente de que o banco continua na versão nova.

Todo site criado no PrimeForge nasce atômico — não há nada a ligar. A seção Configurações e script de deploy ainda deixa você escolher quantas releases manter no servidor (as mais antigas são podadas depois de cada deploy bem-sucedido).

Próximos passos

  • Daemons e Workers — processos supervisionados, pools de fila e escalonamento de workers

  • Terminal — um shell no servidor, no contexto do usuário do site

  • Modo de Pânico — o kill-switch de emergência para tirar um site do ar na hora