# Pause e unpause de apps

O Runner permite pausar uma app manualmente ou automaticamente. Uma app pausada é ignorada pelo cron fetch --deploy até ser reativada. Esta página cobre os dois casos, como diferenciá-los e quando usar cada um.

# Pré-requisitos

• Runner v2.30.10+ (para runner pause)
• Runner v2.23.19+ (para runner unpause e auto-pause)
• App registrada e com state ativo

# Pause manual

runner pause <app>

Define status = "paused" no state da app. A partir daí, o cron skipa a app silenciosamente.

O comando é idempotente — pausar uma app já pausada não gera erro.

# Pausar pelo slug projeto/sistema
runner pause meu-projeto/front

# Pausar pelo path absoluto
runner pause /data/apps/meu-projeto/front

# Ver confirmação em JSON
runner pause meu-projeto/front --json

# Quando usar

# Unpause manual

runner unpause <app>

Volta status para active e reseta consecutive_fetch_errors para 0. O cron volta a processar a app no próximo ciclo.

runner unpause meu-projeto/front

# Com JSON para confirmar os campos resetados
runner unpause meu-projeto/front --json

Se a app não estava pausada, o comando ainda zera consecutive_fetch_errors (comportamento defensivo):

# App app-saudavel was not paused (consecutive_fetch_errors cleared anyway).

# Auto-pause por falhas consecutivas (v2.23.19)

O runner pausa apps automaticamente quando o fetch falha muitas vezes seguidas. Isso acontece quando o runner não consegue nem alcançar o repositório — erro de rede, repo removido do GitHub, token expirado.

O threshold é global, configurado em /opt/runner/config.yml:

max_consecutive_fetch_errors: 10   # default; 0 = desabilita

O runner mantém consecutive_fetch_errors no state de cada app. A cada fetch que falha, incrementa. A cada fetch bem-sucedido, zera.

consecutive_fetch_errors = 0   → normal
consecutive_fetch_errors = 5   → warnings nos logs
consecutive_fetch_errors = 10  → status = "paused", cron skipa

# Causas comuns de auto-pause

# Como identificar uma app auto-pausada

runner status minha-app

O output mostra status: paused e o valor de consecutive_fetch_errors. Use isso para distinguir auto-pause de pause manual (no auto-pause, o contador é maior que zero).

# JSON para automação / scripts de alerta
runner status minha-app --json

# Diferença entre pause manual e auto-pause

Ambos resultam em status = "paused", mas os contadores diferem:

O runner unpause trata os dois casos da mesma forma: reseta o contador e volta para active.

# Sequência típica de manutenção

# 1. Pausar antes de começar
runner pause meu-app/sys

# 2. Confirmar que está pausada
runner status meu-app/sys

# 3. Executar a manutenção (migração, troca de secrets, etc.)
# ...

# 4. Reativar
runner unpause meu-app/sys

# 5. Verificar que o próximo fetch funciona
runner fetch meu-app/sys --deploy

# Sequência após auto-pause

# 1. Verificar o motivo
runner status minha-app
runner debug last-error minha-app

# 2. Corrigir o problema upstream
# (restaurar repo, atualizar token, resolver rede)

# 3. Reativar
runner unpause minha-app

# 4. Forçar fetch para confirmar que o problema foi resolvido
runner fetch minha-app --deploy

# Links relacionados

• GitOps mode — como o cron fetch --deploy funciona
• Status, logs e health — observabilidade para diagnóstico
• runner pause — referência completa
• runner unpause — referência completa
• Retry-exhausted — recuperar após commits que falham (em breve)