# runner pause / runner unpause

runner pause marca uma app como paused: o cron fetch --deploy a ignora completamente até que seja despausada. A app continua rodando em produção — apenas novos deploys são bloqueados. Disponível desde v2.30.10.

runner unpause reverte o estado, reativando a app para deploys automáticos. Disponível desde v2.23.19.

Use quando: você precisa de um emergency stop — impedir que um novo push acidental na branch dist acione um deploy durante manutenção, sem precisar desregistrar a app.

# Sintaxe

runner pause [OPTIONS] <APP>
runner unpause [OPTIONS] <APP>

# Flags (pause)

# Flags (unpause)

# O que fica registrado (v2.165.0+)

Toda pausa grava no state da app a nota, quem pausou, a origem e quando:

O unpause tira essa marca do state. O histórico fica em /opt/runner/logs/pause-events.jsonl, com um evento app_paused e um app_unpaused por ciclo. O campo actor diz quem executou cada evento.

# Exemplos

# Pausar com o motivo

runner pause meu-app --motivo "LE rate limit no tester; DNS ainda não aponta"

App meu-app paused. `runner fetch --deploy` will SKIP it.
  manual · "LE rate limit no tester; DNS ainda não aponta" · por leo (cli) · desde 2026-10-24T14:23:23Z
To resume: runner unpause meu-app

# Verificar estado

runner status meu-app

[PAUSED]  production  v1.0.1   healthy  meu-app.exemplo.com
  │  paused     manual · "LE rate limit no tester; DNS ainda não aponta" · por leo (cli) · desde 2026-10-24T14:23:23Z
  │  Retomar o deploy automático  runner unpause meu-app

O runner list também mostra [PAUSED]. Em JSON, o status traz o bloco paused (reason, note, at, by, origin) e o list traz paused: true.

# Reativar após manutenção

runner unpause meu-app

App meu-app unpaused (had 0 consecutive errors, paused_reason=manual).
  estava: manual · "LE rate limit no tester; DNS ainda não aponta" · por leo (cli) · desde 2026-10-24T14:23:23Z

# Ver o histórico

grep '"app":"meu-app"' /opt/runner/logs/pause-events.jsonl

# Output JSON

$ runner pause meu-app --json
{
  "app": "meu-app",
  "previous_status": "active",
  "status": "paused"
}

$ runner unpause meu-app --json
{
  "app": "meu-app",
  "was_paused": true,
  "status": "active"
}

# Diferença entre pause manual e auto-pause

O runner também pausa apps automaticamente quando max_consecutive_fetch_errors é atingido (default: 10 falhas consecutivas). Ambos os tipos de pause são resolvidos com runner unpause.

Despausar sem corrigir o problema em auto-pause fará a app entrar em loop e ser pausada novamente.

# Fluxo de manutenção

# 1. Bloquear deploys automáticos
runner pause meu-app

# 2. Realizar manutenção (atualização de config, migração, etc.)
runner secrets set meu-app DB_HOST "novo-host"
runner deploy meu-app   # deploy manual ainda é possível enquanto pausado

# 3. Liberar deploys automáticos
runner unpause meu-app

O runner deploy manual funciona mesmo com a app pausada. O pause afeta apenas o ciclo automático do cron.

# Idempotência

runner pause é idempotente: pausar uma app já pausada não gera erro. runner unpause em app não pausada zera consecutive_fetch_errors de forma defensiva, sem erro.

# Erros comuns

• app_not_found — app não registrada neste servidor; verifique com runner list.

# Veja também

• `runner status` — verificar o estado atual da app
• `runner deploy` — deploy manual (funciona mesmo com app pausada)
• `runner fetch` — ciclo automático que respeita o estado paused
• `runner reset` — limpa estado completo (alternativa mais destrutiva)