A resposta curta
Deploy com git push são três decisões: qual branch faz deploy, o que conta como mudança nesse app e o que precisa passar antes. Um push só deve enfileirar um deployment quando algo nesse app mudou e os checks do GitHub já passaram.
Esses ajustes ficam num serviço conectado ao GitHub. A referência é Deploy from Git. As notas de 5 e de 21 de outubro são Wait for CI e Watch paths.
Como funciona o deploy por push
Conecte um repositório ao criar o serviço. A Unbroker guarda o repositório, o branch e o commit que disparou cada deployment.
Num serviço conectado ao GitHub, com deploys automáticos ligados, um push no branch configurado enfileira um deployment. A conexão da Unbroker com o GitHub é o que recebe esse push. Isso é o deploy automático do GitHub. Para fazer deploy de um repositório do GitHub no push, os deploys automáticos precisam estar ligados, e o push precisa ser esse branch. O deploy manual continua disponível no console e na CLI.
O deployment passa por queued, building, deploying e live. Um health check que falha não é tratado como live. O mapa está no overview de deployments. O passo a passo da CLI é Deploy an app from Git.
Escolha o branch que faz deploy
O branch que você configura é o que um push publica. Aponte o serviço de produção para o branch que você libera.
Os outros branches vão para um preview de pull request quando esse recurso está ligado. Previews exigem Pro. Quando estão habilitados num serviço de produção, abrir ou atualizar um pull request cria ou atualiza o preview e faz deploy do head do pull request. O GitHub entrega esses eventos pela conexão do repositório. Previews herdam o Wait for CI do serviço. Como manter um preview longe dos dados de produção está em Ambientes de preview por pull request.
Um serviço Node começa em Deploy de Node.js. Um app Next.js começa em Deploy de Next.js.
Watch paths num monorepo
Watch paths é como um monorepo faz deploy só do app que mudou. Defina os padrões ao criar um serviço de repositório, em Build & deploy, ou depois em Source. Um padrão por linha, relativo à raiz do repositório, mesmo com Root directory definido. Um deploy por Watch paths roda quando um arquivo correspondente é adicionado, modificado ou removido.
apps/web/**
packages/sdk/**
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
.dockerignore
* casa zero ou mais caracteres dentro de um segmento. ? casa um caractere. Um segmento ** inteiro casa zero ou mais segmentos, como em apps/**/Dockerfile. Arquivos ocultos entram. Exclusões não são suportadas: a lista não consegue tirar um path. Inclua pacotes compartilhados, lockfiles e Dockerfiles que afetem o build. O exemplo acima é o da documentação de Git: apps/web, packages/sdk, os lockfiles e .dockerignore.
Padrões configurados substituem o filtro de push do root directory. Eles não mudam o contexto de build. Uma lista vazia mantém o comportamento atual: observa o root directory quando existe um, senão o repositório inteiro. O campo da API é watchPaths. Envie [] para limpar. A mudança vale para os pushes seguintes e não faz redeploy do serviço sozinha.
O filtro roda antes de Wait for CI. Deploys manuais, deploy hooks e previews de pull request não são afetados. Se o repositório é um arquivo Compose, e não um diretório por app, o mapa desse arquivo para serviços está em Docker Compose em produção.
Quando a Unbroker faz deploy mesmo assim
O filtro de paths confia na lista de arquivos que o GitHub envia. Se essa lista está incompleta, o push é um force push, ou um push grande passa do orçamento de trabalho do webhook, a Unbroker faz deploy de forma conservadora. Um commit cuja lista está completa e vazia não dispara um serviço filtrado por paths.
Wait for CI
Wait for CI é o ajuste para fazer deploy só depois do CI passar. Ligue nas configurações do serviço e o push não entra em deploy na hora. A Unbroker espera cada check do GitHub naquele commit terminar e faz deploy se todos passaram. É assim que se espera os checks do GitHub antes do deploy.
O GitHub descreve dois tipos de status checks: checks criados por GitHub Apps, inclusive GitHub Actions, e commit statuses criados por serviços externos. O ajuste da Unbroker segue os checks do GitHub naquele commit. Ele não está documentado como um filtro que aceite só Actions.
O ajuste traz três tempos:
- Um push mais novo, enquanto um commit ainda espera, substitui esse commit.
- Um commit que nunca recebe um check entra em deploy depois de dois minutos.
- Se o CI não termina, o commit é descartado depois de duas horas.
Watch paths roda primeiro. Um push que não casa com nenhum padrão não chega na espera. A nota de origem é Wait for CI before deploying. A descrição do GitHub desses checks é About status checks.
O que um deploy Live não prova
Live quer dizer que o health check passou e que o tráfego pode chegar nessa revisão. Não prova cada rota. Quando o deployment está live, chame um endpoint que você espera e leia a resposta. Um processo saudável não prova cada função, nem uma leitura de banco nem um caminho autenticado.
Uma migração é um passo de release separado. Migrações de banco de dados no deploy é esse passo: roda uma vez, antes de a versão nova receber tráfego, e um rollback de código não desfaz o schema. Comandos de migração exigem Pro. Um rollback promove um deployment conhecido e não reconstrói o commit de origem. Ele pula o comando de pre-deploy e não restaura um banco nem um volume, então a migração precisa continuar segura depois dessa promoção. A frase do rollback está na CLI de deployments. Os limites de pre-deploy e de banco estão em Deixar um agente fazer deploy com cuidado. As linhas do plano estão em Plans.
GitLab e Bitbucket
A regra de push acima vale para um serviço conectado ao GitHub. Merge requests do GitLab e do Bitbucket usam o deploy hook do serviço. Deploy hooks genéricos exigem Pro. Previews de pull request também exigem Pro. Credenciais de repositório privado exigem Pro.
Pro é um compromisso mensal de $25 com $25 de crédito de uso em cada ciclo. O crédito não acumula. Se o uso elegível fica abaixo de $25, a cobrança continua $25. Os valores atuais estão em preços.
Pelo terminal
Criar um serviço pela CLI pede uma organização Pro e um token de API. Apps Free elegíveis podem ser criados no Cloud. O comando documentado é:
ubctl apps services create <projectId> \
--name api \
--repo https://github.com/acme/api \
--framework node
Depois, uma espera. --wait devolve um código de saída diferente de zero quando o deployment falha:
ubctl apps deploy <serviceId> --wait
Um agente de código pode rodar os mesmos comandos. O que ele pode fazer está em Deploy com Claude Code. O que o token não deve ver, e o que um rollback pula, está em Deixar um agente fazer deploy com cuidado.
Checklist
- Conecte o repositório do GitHub e deixe os deploys automáticos ligados.
- Defina o branch que deve fazer deploy. Para os outros, use um preview de pull request, no Pro.
- Num monorepo, defina Watch paths a partir da raiz. Inclua o app, os pacotes compartilhados, os lockfiles e o Dockerfile.
- Deixe a lista vazia só quando o root directory, ou o repositório inteiro, deve fazer deploy.
- Ligue Wait for CI quando um push deve esperar cada check do GitHub passar.
- Quando o deployment estiver live, chame um endpoint real.
- Trate migrações como um passo próprio. Um rollback não reconstrói o commit e não restaura um banco.
Perguntas frequentes
A Unbroker faz deploy automático do GitHub em todo push?
Um serviço conectado ao GitHub, com deploys automáticos ligados, enfileira um deployment quando o push cai no branch configurado. Os outros branches não seguem esse caminho. Watch paths pode limitar a fila aos arquivos que coincidem. O deploy manual continua disponível no console e na CLI. A regra está em Deploy from Git.
Dá para fazer deploy só depois do CI do GitHub Actions passar?
Wait for CI espera cada check do GitHub naquele commit terminar e faz deploy se todos passaram. GitHub Actions é um jeito de criar esses checks. O ajuste não está documentado como exclusivo do Actions. Um push mais novo substitui o commit que está esperando. Se o CI não termina, esse commit é descartado depois de duas horas.
E se o repositório não tem checks de CI?
Um commit que nunca recebe um check entra em deploy depois de dois minutos. A nota de Wait for CI diz isso para um repositório sem CI não ficar esperando.
Como evitar que um monorepo faça deploy de cada app?
Defina Watch paths, um padrão por linha, relativo à raiz do repositório. Inclua esse app, os pacotes compartilhados, os lockfiles e o Dockerfile. Uma lista vazia mantém o comportamento anterior: o root directory quando existe um, senão o repositório inteiro.
Watch paths afeta deploys manuais ou previews de pull request?
Não. Deploys manuais, deploy hooks e previews de pull request ignoram Watch paths. O filtro vale para deploys automáticos por push e roda antes de Wait for CI.
Dá para fazer deploy a partir do GitLab ou do Bitbucket?
Merge requests do GitLab e do Bitbucket usam o deploy hook do serviço. Deploy hooks genéricos exigem Pro. A regra de push em Deploy from Git está escrita para um serviço conectado ao GitHub.
Push-to-deploy está no Free?
A tabela de planos não tem uma linha chamada push-to-deploy. O Free inclui Node.js gerenciado e 3 deploy requests por dia UTC. Deploys não usados não acumulam. Previews de pull request, deploy hooks genéricos e credenciais de repositório privado não estão no Free. O Pro não tem teto de requests do plano.