# runner serve

Inicia o servidor de triggers para receber webhooks e/ou executar o canary scheduler.

# Sintaxe

runner serve [OPTIONS]

# Opcoes

Nota v2.2.0: em service mode (--service), port/mode/secret vem do service.yml e nao dos argumentos CLI.

# Modos de Operacao

# Exemplos

# Auto-detectar Modo

runner serve

Se WEBHOOK_SECRET estiver definido, inicia webhook + cron. Senao, apenas cron.

# Apenas Webhook Server

runner serve --mode webhook --port 9000

# Apenas Canary Scheduler

runner serve --mode cron --tick-interval 30

# Ambos

runner serve --mode both --port 8080 --tick-interval 60

# Com Secret via Argumento

runner serve --secret "meu_secret_aqui"

# Com Secret via Variavel de Ambiente

export WEBHOOK_SECRET="meu_secret_aqui"
runner serve

# Webhook Server

O webhook server recebe eventos de push do GitHub (headers X-Hub-Signature-256 e X-GitHub-Event).

Estado atual: o webhook valida a assinatura e responde ao ping, mas o push ainda não dispara deploy. O deploy continua vindo do cron (runner fetch --deploy) ou da API do service mode.

Desde a v2.161.0, com --secret o webhook escuta em todas as interfaces, para o GitHub alcançar. Sem secret ele não sobe, salvo com --allow-unauthenticated, que escuta só em 127.0.0.1.

# Endpoints

# Eventos Suportados

# Headers Esperados

# Payload GitHub

{
  "ref": "refs/heads/dist",
  "repository": {
    "full_name": "usuario/repo",
    "name": "repo"
  },
  "pusher": {
    "name": "usuario"
  },
  "after": "abc123..."
}

# Verificacao de Assinatura

Se secret estiver configurado, o servidor verifica a assinatura HMAC-SHA256:

1. Calcula HMAC-SHA256 do body com o secret
2. Compara com o header X-Hub-Signature-256
3. Rejeita se nao corresponder (401 Unauthorized)

# Canary Scheduler

O canary scheduler executa periodicamente (a cada tick-interval segundos) e:

1. Le estado dos canary deployments ativos
2. Verifica health checks
3. Incrementa peso se configurado para auto-promote
4. Executa rollback se condicoes de abort forem atingidas

# Estado do Scheduler

O estado e persistido em /opt/runner/state/canary/:

# /opt/runner/state/canary/meu-app_production.yml
project: meu-app
instance: production
stable_version: v1.2.3
canary_version: v1.2.4
current_weight: 30
state: running
started_at: "2026-02-16T14:00:00Z"
last_step_at: "2026-02-16T14:10:00Z"
next_step_at: "2026-02-16T14:15:00Z"

# Logs do Scheduler

# Ver logs em tempo real
tail -f /opt/runner/logs/canary-scheduler.log

# Ou via journalctl se rodando como servico
journalctl -u runner-serve -f

# Configuracao via config.yml

O comando serve le configuracoes do config.yml:

# /opt/runner/config.yml
triggers:
  mode: auto
  webhook:
    enabled: true
    port: 8080
    path: /webhook
    secret: "${WEBHOOK_SECRET}"
  cron:
    enabled: true
    canary_tick_interval: 60

Argumentos da CLI sobrescrevem o config.yml.

# Service Mode (v2.2.0+)

A forma recomendada de rodar o serve em producao e via service mode:

runner service init --enable-api    # Gera service.yml + unit; nasce DESATIVADO (v2.161.0)
runner service start                # Liga: inicia e habilita no boot
runner service status               # Verifica

# Todos os subcomandos de `service`

O service mode le /opt/runner/service.yml e inicia:

• API HTTP com auth via X-API-Key (endpoints: /health, /api/v1/status, signal, deploy, apps)
• Scheduler generico com jobs configuraveis (canary, ttl_cleanup, signal_check)
• mTLS opcional (v2.3.0) com hot-reload de CA cert

Desde a v2.161.0:

• sem service.yml, so o scheduler sobe, e a API fica desligada ate o runner service init;
• API habilitada sem chave, ou com chave fora do formato rk_…, nao sobe;
• bind invalido e erro. Antes, a API subia com chave vazia aceitando um header vazio, e um bind invalido virava 127.0.0.1 em silencio.

Ver service.yml reference para configuracao completa.

# API Endpoints (v2.2.0)

# mTLS (v2.3.0)

Quando habilitado, conexoes sem client certificate valido sao rejeitadas no TLS handshake. A CA e relida do disco a cada handshake em que o arquivo mudou (mtime), sem restart. Isso vale desde a v2.161.0; antes so valia depois de reiniciar.

Com o mTLS ligado e faltando ca.pem, server.pem ou server.key, a API nao sobe e mostra mtls_incompleto com a lista do que falta. Antes, sem CA, ela caia para HTTP sem avisar.

runner service config --ca-cert /path/to/ca.pem

O mTLS e para conexao direta. Atras do Traefik (service expose) ele e recusado, porque o Traefik termina o TLS.

# Modo Legacy (compatibilidade)

O modo legacy (sem --service) continua funcionando como antes:

# Systemd (legacy)

# /etc/systemd/system/runner-serve.service
[Unit]
Description=Runner Webhook/Cron Server
After=network.target docker.service

[Service]
Type=simple
ExecStart=/opt/runner/runner serve
WorkingDirectory=/opt/runner
Environment=WEBHOOK_SECRET=seu_secret_aqui
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Configurando GitHub Webhook

1. Acesse Settings → Webhooks no repositorio
2. Clique em "Add webhook"
3. Configure:
   • Payload URL: https://seu.servidor.com:8080/webhook
   • Content type: application/json
   • Secret: Mesmo valor do WEBHOOK_SECRET
   • Events: Just the push event
4. Clique em "Add webhook"

# Testando

# Health Check

curl http://localhost:8080/health

Resposta esperada:

{"status": "healthy", "version": "1.2.0"}

# Simular Webhook

# Gerar assinatura
PAYLOAD='{"ref":"refs/heads/dist","repository":{"full_name":"user/repo"}}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "seu_secret" | cut -d' ' -f2)

# Enviar
curl -X POST http://localhost:8080/webhook \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=$SIGNATURE" \
  -H "X-GitHub-Event: push" \
  -d "$PAYLOAD"

# Exit Codes