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.

#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, Migrations no Deploy, 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.

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 7 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 sete segmentos que acendem um a um, com um cursor piscando no estágio ativo:

Fetch → Infra → Build → 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.

#Build — instala dependências e compila

Roda como o usuário Linux dedicado do site, no diretório da release, e é pulado por completo em sites do tipo HTML Estático. Dependendo do tipo de site:

• Sites PHP/Laravel com composer.json → composer install (e, para sites Laravel que também têm um package.json com script de build, npm install + npm run build).
• Sites Node.js / Next.js → npm install (quando as dependências estão desatualizadas) seguido do build_command configurado.

Se você tem credenciais de pacotes privados cadastradas (Composer auth.json, NPM .npmrc), elas são injetadas apenas durante o build e 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 build — 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.

#Script — migrações e o script de deploy

Para sites Laravel (detectados pela presença do arquivo artisan), o PrimeForge roda automaticamente, nesta ordem:

php artisan migrate --force
php artisan optimize:clear
php artisan storage:link

Em seguida executa o seu deploy.sh e os hooks de pré/pós-deploy (veja O script de deploy e os hooks abaixo). Sites estáticos pulam este estágio inteiro.

Se você prefere rodar as migrações por fora do painel, clique em Desabilitar na linha Migrations no Deploy da seção Configurações e script de deploy da página Deployments. O pipeline passa a pular o php artisan migrate --force (e o rastreamento de schema) — o optimize:clear e o storage:link continuam rodando, e o log do deploy registra Migrations skipped (disabled in site settings). A partir daí a responsabilidade de migrar o banco é sua.

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

Quando um deploy falha, o log daquele deploy mostra:

• Estágio da falha — em qual etapa o deploy abortou ("Falhou em: Build", 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.

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

Além dos passos automáticos, você pode injetar comandos próprios no pipeline. 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:

Os três scripts rodam no servidor como o usuário Linux dedicado do site, no diretório da release, e persistem entre as releases. Hooks vazios são pulados em silêncio. O deploy.sh é o lugar certo para comandos como php artisan config:cache, reinício de filas ou aquecimento de cache.

Ao lado do editor, Snippets e variáveis traz blocos prontos para Inserir ou Copiar — Laravel completo, artisan optimize, artisan migrate --force, storage:link, reiniciar workers ou o Horizon, recarregar o Octane, npm ci + build, pnpm install + build — e lista as variáveis que os scripts recebem, como PF_PHP (o binário php da versão do site), PF_SITE_PATH, PF_RELEASE_PATH, PF_SHARED_PATH, PF_DOMAIN, PF_BRANCH e PF_SITE_USER.

#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 build e as migrações terminam com sucesso.

O efeito prático é importante:

• Falha antes da troca é invisível — se o deploy falha no Fetch, Build 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 acompanha a contagem de migrações antes e depois de cada 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