# Staging de PRs

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

# Conceito

Pull Request #42
    |
    | runner stage deploy --pr 42
    v
Ambiente Staging
  URL: pr-42.staging.meusite.com.br
  TTL: 48 horas
    |
    | Testes, review
    v
  Merge ou Close
    |
    | Cleanup automatico
    v
Ambiente destruido

# Configuracao

# 1. Configurar DNS Wildcard

Configure um registro wildcard no seu DNS:

*.staging.meusite.com.br  →  IP_DO_SERVIDOR

# 2. Configurar .deploy.yml

Adicione a secao de staging:

instances:
  production:
    domain: app.meusite.com.br
    source:
      type: dist

  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

# 3. Configurar config.yml (Global)

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

# 4. Instalar GitHub CLI

O staging usa gh para clonar branches de PRs:

# Instalar
apt install gh

# Autenticar
gh auth login

# Uso

# Criar Staging

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

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_meu-app_pr42

# Cleanup Automatico

runner stage cleanup

Remove todos os stagings que passaram do TTL.

# Variaveis de Template

# Cron de Cleanup

Configure cleanup automatico:

# crontab -e
0 * * * * /opt/runner/runner stage cleanup --json >> /var/log/runner-staging-cleanup.json 2>&1

# Limites

# Por Projeto

Configurado em staging.max_instances no .deploy.yml:

staging:
  max_instances: 5

# Global

Configurado em staging.max_total_instances no config.yml:

staging:
  max_total_instances: 20

# Quando Limite e Atingido

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

# Fluxo de Trabalho

# Desenvolvedor

1. Cria PR no GitHub
2. Executa runner stage deploy --pr 42
3. Testa em pr-42.staging.meusite.com.br
4. Faz ajustes, commits
5. Redeploya staging (automatico ou manual)
6. Merge da PR
7. Staging destruido no cleanup

# Automacao via CI

Adicione ao workflow do GitHub:

# .github/workflows/staging.yml
name: Staging

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: self-hosted
    steps:
      - name: Deploy staging
        run: |
          runner stage deploy --repo ${{ github.repository }} --pr ${{ github.event.pull_request.number }} --json

# Redeploy de PR

Se fizer novos commits na PR:

# Destroi e recria
runner stage deploy --repo usuario/meu-app --pr 42

O Runner detecta staging existente e recria automaticamente.

# Troubleshooting

# DNS nao resolve

Verifique wildcard DNS:

dig pr-42.staging.meusite.com.br

# GitHub CLI nao autenticado

gh auth status
gh auth login

# Container unhealthy

docker logs staging_meu-app_pr42 --tail 100

# Max instances atingido

# Listar todos
runner stage list

# Destruir antigos
runner stage destroy --id staging_meu-app_pr35
runner stage destroy --id staging_meu-app_pr38

# Ou cleanup automatico
runner stage cleanup

# Boas Praticas

# TTL Adequado

• PRs rapidas: 24h
• Features grandes: 72h
• Reviews demorados: 168h (1 semana)

# Naming Convention

Use domain_pattern consistente:

• pr-${PR_NUMBER}.staging.${DOMAIN} - Padrao
• ${BRANCH}.staging.${DOMAIN} - Por branch
• ${PR_NUMBER}-${HASH}.staging.${DOMAIN} - Com hash

# Recursos

Stagings consomem recursos. Monitore:

• Numero de containers
• Uso de memoria/CPU
• Espaco em disco