# runner stage

Comandos para gerenciar ambientes de staging de Pull Requests.

# Visao Geral

O staging permite criar ambientes efemeros para testar Pull Requests antes do merge.

# Comandos

# Deploy de PR

runner stage deploy --repo <user/repo> --pr <number> [--json]

Parametros:

• --repo: Repositorio GitHub (usuario/repo)
• --pr: Numero da Pull Request
• --json: Output em JSON

Exemplo:

runner stage deploy --repo usuario/meu-app --pr 42

Output:

Staging deployed:
  ID: staging_meu-app_pr42
  URL: https://pr-42.staging.meusite.com.br
  TTL: 48h (expira em 2026-02-14 10:30)

# Listar Stagings

runner stage list [--json]

Exemplo:

runner stage list

Output:

Stagings ativos:
  staging_meu-app_pr42
    URL: pr-42.staging.meusite.com.br
    Status: healthy
    TTL: 46h restantes

  staging_outro-app_pr15
    URL: pr-15.staging.outrosite.com.br
    Status: healthy
    TTL: 12h restantes

# Destruir Staging

runner stage destroy --id <staging_id>

Exemplo:

runner stage destroy --id staging_meu-app_pr42

# Cleanup Automatico

runner stage cleanup [--json]

Este comando:

1. Lista todos os stagings
2. Remove os que passaram do TTL
3. Libera recursos (containers, config, diretorios)

# Configuracao

# No .deploy.yml

instances:
  pr:
    domain_pattern: "pr-${PR_NUMBER}.staging.meusite.com.br"
    source:
      type: pr
    ephemeral: true
    ttl_hours: 48

staging:
  enabled: true
  max_instances: 5
  ttl_hours: 48

# No config.yml (Global)

staging:
  enabled: true
  base_path: /opt/runner/staging
  network: public
  default_ttl_hours: 48
  max_total_instances: 20

# Variaveis de Template

# Cron de Cleanup

Configure cleanup automatico no crontab:

# Cleanup a cada hora
0 * * * * /opt/runner/runner stage cleanup --json >> /var/log/runner-staging-cleanup.json 2>&1

# Requisitos

# DNS Wildcard

Configure um registro wildcard no DNS:

*.staging.meusite.com.br  →  IP_DO_SERVIDOR

# GitHub CLI

O comando stage deploy usa gh para clonar a branch da PR:

# Verificar instalacao
gh --version

# Autenticar
gh auth login

# Limites

• Por projeto: staging.max_instances (default: 3)
• Global: staging.max_total_instances (default: 20)

Se o limite for atingido:

runner stage deploy --repo usuario/meu-app --pr 43
# Error: max instances reached (5/5). Destroy an existing staging first.

# Exit Codes