Deploys e Rollback

Um deploy é o processo que leva o código do seu repositório Git até o container que serve o seu site. 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 aba 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 aba Deployments na barra de navegação de qualquer site, ao lado de Overview, Environment, Logs e Daemons.

#A aba Deployments

A aba Deployments reúne tudo o que você precisa para operar os deploys de um site:

• 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 (Sucesso, Falha, Em andamento, Pulado), o commit, a branch, quem disparou e quanto tempo levou.
• Botão de deploy manual — dispara um novo deploy imediatamente a partir da branch configurada.
• Log do último deploy — o painel ao vivo que mostra o pipeline estágio a estágio.
• Editor do script de deploy — onde você personaliza os comandos que rodam ao final do pipeline (deploy.sh) e os hooks de pré e pós-deploy.

Cada linha do histórico é clicável e abre o log completo daquele deploy, útil para investigar uma falha antiga ou conferir exatamente o que rodou em uma versão específica.

#Disparar um deploy manual

Clique em Deploy (disponível também na página Overview do site). O PrimeForge abre o modal de confirmação, onde você revisa a branch de destino antes de iniciar. Ao confirmar, um novo deploy entra na fila e o log ao vivo começa a rolar.

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, a aba 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 — sobe os containers

Garante que os containers Docker do site estejam no ar e que o arquivo de configuração (Docker Compose) esteja atualizado com as opções atuais do site (banco, Redis, Horizon, Reverb, etc.). Este estágio converge sem reiniciar à força o container que já está servindo tráfego — ele nunca derruba a versão que está no ar. A recriação de fato acontece só no estágio Restart, depois da troca.

#Build — instala dependências e compila

Roda dentro do container 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 de novo" 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, desligue Site → Settings → Rodar migrações. 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 registra "Migrações puladas (desativadas nas configurações do site)". A partir daí a responsabilidade de migrar o banco é sua.

#Restart — recria os containers

Recria os containers da aplicação 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 Falha — 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.

Quando um deploy falha, o painel Log do último deploy mostra:

• Estágio da falha — em qual etapa o deploy abortou (por exemplo, "Build" ou "Health Check").
• 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 novamente (reexecuta como está), Cancelar deploy (encerra um deploy travado no meio) 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).

#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. Você liga/desliga em Site → Settings → Serviços → Auto Deploy; a mesma linha mostra a URL de webhook do site com um botão de copiar.

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 Pulado 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 na aba Deployments tem três abas, uma para cada arquivo:

Os três scripts rodam dentro do container do site, como o usuário primeforge, 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.

#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 o Rollback. A ação está disponível nas páginas Overview e Deployments do site e reaponta o current para a release anterior — a versão antiga volta ao ar em segundos, sem rebuild. 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.

Sites legados (criados antes das releases atômicas, que faziam deploy no lugar) podem aderir ao layout atômico pela página Settings do site; a mesma opção reverte. Sites que já nasceram atômicos não mostram essa opção.

#Próximos passos

• Daemons e Workers — processos supervisionados e escalonamento de filas
• Terminal — um shell no servidor ou dentro do container do site
• Modo de Pânico — o kill-switch de emergência para tirar um site do ar na hora