A resposta curta
Um deploy com falha para numa etapa. Nomeie essa etapa pela evidência que ela deixou, e só então mude a menor coisa que a explica. Fazer outro deploy antes de saber a etapa pode esconder essa evidência.
A Unbroker registra o commit, a saída do build, o rollout e o estado final de saúde. O corte mais fino, de um erro de clone até um comando post-deploy, é como se lê uma falha concreta. O passo a passo para um agente está em Diagnose a failed deployment.
As etapas de um deployment
Um deployment transforma uma revisão do código num serviço em execução. O overview de deployments lista quatro etapas:
- Queued. O deployment foi aceito e atribuído ao sistema de build.
- Building. As dependências são instaladas e o artefato ou a imagem de produção é criado.
- Deploying. A revisão nova entra no ar e passa pelo health check.
- Live. O tráfego pode chegar à revisão saudável.
Um health check que falha impede que uma revisão doente seja tratada como live. Revise os logs de build e de runtime antes de tentar de novo. O overview não descreve uma nova tentativa automática, e não descreve um rollback automático.
Se o push nunca enfileirou um deployment, a falha é anterior a essas quatro etapas. Qual branch publica, quais caminhos contam e quando a Unbroker espera os checks está em Deploy com git push. A espera em si é Wait for CI.
Para acompanhar um deployment até o fim:
ubctl apps deploy <serviceId> --wait
--wait consulta até o deployment chegar a um estado terminal e devolve um código diferente de zero quando falha. Esse comportamento está na CLI de deployments.
Log do deployment e logs de runtime
A saída do deployment descreve o build e a tentativa de release. Os logs do serviço descrevem o processo em execução. Confirme os timestamps e a revisão de origem para não estar lendo um deployment antigo ou outro ambiente.
ubctl whoami
ubctl apps services get <serviceId>
ubctl apps deployments <serviceId>
ubctl apps deployment <deploymentId> --log
ubctl apps services logs <serviceId> --since 30m
Troque os placeholders pelos ids dessa falha. ubctl whoami confirma a organização ativa antes de você ler qualquer outra coisa. Esses comandos são o passo de juntar evidência no guia.
Logs, metrics, and monitoring separa os mesmos sinais. Como esses sinais viram alertas, e o que eles não alcançam, está em Logs, métricas e alertas. O log de build diz por que uma revisão construiu ou não. O log de runtime é o que a aplicação em execução escreve. O histórico de deployments diz o que mudou e qual revisão está live. As linhas de runtime ficam guardadas por 7 dias. A saída do build fica em cada deployment. Saída de build com mais de 90 dias é removida, exceto a do deployment que o serviço está rodando agora. Um deploy posterior é outro registro. Ler o commit errado, a hora errada ou outro ambiente é como a evidência se esconde.
Classifique a falha
| Etapa | Evidência útil | Próxima verificação |
|---|---|---|
| Código-fonte ou instalação de dependências | Erros de clone e de instalação | Acesso ao repositório, o lockfile e a origem das dependências |
| Compilação | O primeiro erro de compilador ou de build sobre o qual dá para agir | Comando de build, versão do runtime e saída esperada |
| Subida | A saída do processo e a primeira exceção de runtime | Comando de start, arquivos faltando ou variáveis obrigatórias |
| Health check ou roteamento | Endereço de escuta e resposta da sonda | PORT, 0.0.0.0, o path do endpoint e a duração da subida |
| Request da aplicação | Status HTTP e o erro daquele request | Conectividade com o banco, migrações ou lógica da aplicação |
| Comando post-deploy | postDeployStatus: failed com o deployment em live, mais a saída do comando no log do deployment. Se o control plane para durante o comando, o mesmo status é registrado e o comando não roda de novo | O comando, o timeout e as variáveis do serviço. O release não é revertido |
A tabela é a do guia. Memória esgotada não é uma linha própria. Trate como evidência, e veja se aconteceu durante o build ou durante a execução antes de mudar um ajuste. São etapas diferentes.
Falhas de build: dependências e compilação
Uma falha de build fica em Building. O deployment não chega ao health check.
Comece pelo acesso ao repositório, pelo lockfile e por de onde vêm as dependências. O guia de Node.js manda commitar o lockfile que o package manager gerou. Se o build instala pacotes privados, o guia de Docker manda passar o token como segredo do BuildKit, com o nome que a ferramenta espera. Tokens não entram como argumentos de build.
Use o primeiro erro de compilador ou de build sobre o qual dá para agir. Depois confira o comando de build, a versão do runtime e se a saída esperada existe. Num log de build muito grande, a Unbroker guarda o começo e a saída mais recente, então a última linha não é o único lugar para olhar. Essa regra de retenção está na documentação de monitoring.
Com Bun, um repositório que tem bun.lock ou bun.lockb na raiz é instalado e construído com Bun. Se você não fixa uma versão, os builds usam Bun 1.4.2. Um pin exato é lido de "packageManager" no package.json, depois de um arquivo .bun-version, e depois de "engines". O [email protected] da documentação é um exemplo de pin exato, não o padrão. Só versões exatas a partir de 1.2.0 são respeitadas. Um intervalo como >=1.1 usa o padrão. O log de build diz qual versão foi usada e por quê. Um server cujo comando de start usa Bun roda nessa mesma versão. A fonte é service types.
Um build com Dockerfile usa a imagem base desse arquivo. O exemplo do guia de Docker é FROM node:22-slim. Essa tag é o exemplo, não um padrão da plataforma. O guia de Fastify manda conferir se a versão de Node.js escolhida atende o que a versão instalada do Fastify exige.
Falhas de subida: o processo encerra
A imagem existe, e o processo encerra antes de conseguir atender. A evidência é essa saída e a primeira exceção de runtime. Confira o comando de start, os arquivos que faltam e as variáveis de que o processo precisa.
O guia de Node.js cita três causas típicas: um script de start ausente, um arquivo compilado que nunca foi gerado, e uma variável de ambiente exigida durante a subida. Um app em TypeScript precisa de um build que produza JavaScript e de um comando de start que aponte para essa saída. O guia de Fastify manda inspecionar o primeiro erro de subida antes de tentar de novo. O guia de FastAPI diz que um erro de import em geral significa que o path do módulo não bate com o repositório, ou que uma dependência ficou de fora, e que você leia os logs de runtime antes de aumentar recursos.
Se falta uma variável, grave o valor no Cloud. Não coloque o valor num prompt nem num log copiado. Esse passo é Environment variables.
Health check e roteamento
Deploying inclui o health check. Uma verificação que falha impede que essa revisão seja tratada como live.
O processo tem que escutar em 0.0.0.0 e na PORT recebida, não num localhost fixo. O guia de Node.js diz que um build bem-sucedido, sozinho, não prova que o server está acessível. EXPOSE num Dockerfile não sobe um server nem publica uma porta. Quem faz isso é o listener. Escutar só em localhost é uma diferença comum entre um processo que funciona na sua máquina e um contêiner que ninguém alcança. Essa frase está no guia de Fastify.
As outras verificações são o path do endpoint e a duração da subida. Se a sonda chama um path que o app não serve, a verificação falha. No Pro, o guia de Fastify manda apontar o health check do serviço para /health quando essa é a rota. Plans lista health checks avançados como indisponíveis no Free e disponíveis no Pro. A documentação não publica uma quantidade de segundos para a subida. Se o processo ainda está subindo quando a sonda roda, leia o log de runtime e procure a primeira exceção antes de mudar o path.
Um processo sem listener não deve ser forçado por um health check HTTP. Use um worker. O guia do worker diz que workers com Dockerfile rodam sem URL pública e sem sonda de readiness HTTP. Como um arquivo Compose se reparte nesses serviços está em Docker Compose em produção.
Ficou live, mas um endpoint falha
Live quer dizer que o health check passou e que o tráfego pode chegar a essa revisão. Não quer dizer que cada rota funciona. Quando o deployment está live, chame o endpoint que importa e leia a resposta.
Se o hostname padrão da Unbroker responde e só o domínio personalizado falha, o deployment já está live. DNS, a verificação do hostname e o certificado são os três estados em Domínio personalizado e HTTPS. Fazer deploy de novo do mesmo commit não conserta isso.
Uma resposta saudável não prova que uma feature dependente de schema funciona. O guia de Fastify diz que a rota de health do exemplo não prova que existe um banco. O guia de Next.js diz que uma home que renderiza não exercita a aplicação inteira. As verificações seguintes são conectividade com o banco, migrações e lógica da aplicação.
Migrações são um passo de release separado. Onde esse comando roda, e por que um rollback deixa o schema no lugar, está em Migrações de banco de dados no deploy.
Memória esgotada: no build ou em execução?
Trate memória esgotada como evidência. Veja se aconteceu durante o build ou com o processo já em execução antes de mudar um ajuste. O guia separa essas etapas.
Se o build fica sem memória, o guia de Next.js manda ver onde: instalação de dependências, compilação ou geração de páginas. Tire trabalho de que o build não precisa, ou ajuste a capacidade que vale para essa etapa. Réplicas extras de runtime não consertam um build que ficou sem memória. O guia de FastAPI manda ler os logs de runtime antes de aumentar recursos: essa é a outra etapa, o processo já está rodando.
No Pro, a aba Resources mostra CPU e memória contra os limites com que o serviço roda. Métricas de recursos são uma função do Pro. Limites de CPU e memória são fixos no Free e configuráveis no Pro. Essas linhas estão em Plans. O comando que muda o limite em execução está em scaling. Use depois que o log disser que o processo em execução é a etapa que ficou sem memória.
O comando post-deploy falhou
Um serviço de repositório pode rodar um comando depois que o deployment já está live. Ele roda numa cópia avulsa da imagem nova, com as variáveis de ambiente desse serviço, por no máximo 10 minutos. A saída é acrescentada ao log do deployment.
Se o comando falha, o deployment continua live e nada é revertido. postDeployStatus é running, succeeded ou failed. O comando não roda quando o próprio deploy falha. Se o control plane para enquanto o comando está rodando, a mesma falha é registrada quando o lease do deploy expira, e o comando não é iniciado de novo.
O comando não monta um volume persistente. Serviços on-demand não precisam estar acordados para isso, e a proteção de acesso privado não se aplica a essa cópia avulsa. Coloque segredos em variáveis de ambiente, não na string do comando. O próprio comando não é impresso no log, e valores longos de ambiente são mascarados.
Comandos post-deploy exigem um plano pago e não estão disponíveis para serviços de imagem. ubctl e infrastructure as code ainda não aceitam o campo. @unbroker/iac v0.2.0 só tem preDeploy. Defina postDeployCommand nos ajustes do serviço, ou com PATCH /apps/services/:id. Mudar o comando marca o serviço para um novo deploy. As fontes são a CLI de deployments e a nota de 26 de outubro.
Recuperar: um deploy novo, ou um rollback
Corrija a causa que você encontrou e faça deploy de novo, esperando o resultado:
ubctl apps deploy <serviceId> --wait
Chame o endpoint afetado. Confirme que a falha original sumiu. Uma resposta saudável continua sem provar uma feature dependente de schema. Inclua uma verificação que exercite essa feature.
Um rollback é a outra recuperação, e é um comando que você executa. A documentação não descreve a Unbroker iniciando um por conta própria.
ubctl apps rollback svc_123 dep_previous
Na documentação, svc_123 e dep_previous representam o serviço e o deployment que você está promovendo. Um rollback promove um deployment conhecido. Ele não reconstrói o commit de origem. Não restaura um banco, um volume nem um efeito externo. Voltar para uma imagem anterior também não desfaz mudanças de configuração nem escritas no banco. Confira o schema e os dados antes de escolher isso. Essas frases estão na CLI de deployments, no guia de diagnóstico e em infrastructure as code. O que isso significa para uma migração está em Migrações de banco de dados no deploy. Um arquivo que sumiu é outra falha, diferente de um crash. Se ele só estava no filesystem do contêiner, Volumes persistentes explica o que sobrevive a um redeploy e o que Reset, Detach e apagar o serviço removem.
No Free, deploy requests são 3 por dia UTC. Os que não são usados não acumulam. O Pro não tem teto de requests do plano. Essa linha está em Plans. É um motivo para classificar a etapa primeiro. Os outros limites desse plano, inclusive o sono e o teto de serviços, estão em limites de deploy e de runtime do plano Free.
Fazer isso na Unbroker
A visão do projeto mostra logs ao vivo, saúde e histórico de deployments de cada serviço. Métricas ficam no Pro. Logs de runtime estão no Free e no Pro. Os comandos acima precisam de um token de API, e tokens de API exigem o Pro. Apps públicos de Node.js elegíveis podem ser criados no Cloud no Free. O guia de Node.js marca esse corte.
Um agente de código pode ler a mesma evidência com o skill ubctl-ops. Enquanto diagnostica, ele não deve mudar recursos. O prompt do guia é:
Use ubctl-ops to diagnose deployment [deployment ID] for service
[service ID]. Confirm the active organization, inspect deployment
output and recent runtime logs, and identify the first actionable
failure. Do not change resources yet. Report the evidence, likely
cause and smallest proposed fix. Redact credentials and user data.
Quando o diagnóstico se sustenta, autorize o conserto específico. Se falta uma variável, grave o valor no Cloud. Não cole no prompt nem num trecho de log. O que o token pode fazer está em Deixar um agente fazer deploy com cuidado. O fluxo de deploy desse agente está em Deploy com Claude Code.
O Pro custa $25 por mês, com $25 de crédito de uso. O crédito reinicia a cada ciclo e não acumula. Se o uso elegível fica abaixo do crédito, a cobrança mensal continua sendo o preço do plano. Os valores atuais estão em preços.
Checklist
- Copie o id do deployment e o id do serviço. Rode
ubctl whoamie confirme a organização. - Leia o log desse deployment e depois os logs de runtime da mesma janela. Confira o commit e o ambiente.
- Nomeie a etapa antes de mudar um ajuste.
- Num build, use o primeiro erro acionável. Confira o acesso, o lockfile e a versão do runtime.
- Se o processo encerra, confira o comando de start, os arquivos que faltam e as variáveis obrigatórias. Grave no Cloud os valores que faltam.
- Num health check, confira
PORT,0.0.0.0, o path e se o processo já está escutando. - Se o deployment está live e um endpoint falha, chame esse endpoint. Uma resposta saudável não prova uma feature dependente de schema.
- Se o erro é de memória, veja se foi o build ou o processo em execução antes de mudar a capacidade.
- Se
postDeployStatuséfailed, o deployment pode continuar live. Leia a saída do comando. Nada foi revertido. - Faça deploy com
--waite chame o endpoint. Faça rollback só quando promover um deployment conhecido for o conserto menor. Um rollback não restaura um banco nem um volume.
Perguntas frequentes
Por que o build passa e o deploy falha?
O artefato foi construído. A falha vem depois, na subida ou no health check. Um health check que falha impede que essa revisão seja tratada como live. Leia os logs de runtime. Causas típicas de subida: falta o script de start, o arquivo compilado não foi gerado, ou falta uma variável de que o processo precisa para subir. O processo também tem que escutar em 0.0.0.0 e na PORT que recebe. As fontes são o guia de Node.js e o overview de deployments.
O que significa health check failed?
A revisão nova não respondeu como saudável, então ela não é tratada como live. Confira o endereço de escuta, o path do endpoint e a duração da subida. O processo deve escutar em 0.0.0.0 e na PORT que recebe, não só em localhost. A documentação não publica uma quantidade de segundos para essa espera. Essas verificações estão em Diagnose a failed deployment.
Basta fazer o deploy de novo?
Não, se você ainda não sabe a etapa. Repetir o deploy sem isso pode esconder evidência útil. O overview de deployments manda revisar os logs de build e de runtime antes de tentar de novo. Ele não descreve uma nova tentativa automática.
Um rollback conserta uma migração quebrada?
Não. ubctl apps rollback promove um deployment anterior e não reconstrói esse commit. Ele não restaura um banco, um volume nem um efeito externo, e não desfaz escritas no banco. Esse limite está em Migrações de banco de dados no deploy.
O comando post-deploy falhou. O app está fora do ar?
Não. O deployment continua live e nada é revertido. postDeployStatus fica failed, e a saída do comando está no log do deployment. O comando roda por no máximo 10 minutos, exige um plano pago e não está disponível para serviços de imagem. Veja a nota de 26 de outubro e a CLI de deployments.