service.yml

Configuracao do Runner quando rodando como servico persistente via systemd. Gerado por runner service init e armazenado em /opt/runner/service.yml com permissoes 0600.

Separado do config.yml (que e a configuracao global lida por todos os comandos). O service.yml so e lido por runner serve --service.

Estrutura Completa

# /opt/runner/service.yml

# ============================================
# API HTTP
# ============================================
api:
  enabled: true           # Expor API HTTP?
  port: 9090              # Porta do server
  bind: "127.0.0.1"       # Interface (127.0.0.1 = local only, 0.0.0.0 = exposto)
  api_key: "rk_a1b2c3d4_e5f6a7b8c9d0e1f2a3b4c5d6"  # Gerada automaticamente

# ============================================
# SCHEDULER (jobs periodicos)
# ============================================
scheduler:
  enabled: true
  tick_interval: 60       # Intervalo base em segundos

  jobs:
    canary:
      enabled: true       # CanaryJob: verifica canaries ativos
    ttl_cleanup:
      enabled: true
      interval: 300       # TtlCleanupJob: limpa PRs/staging expirados (5min)
    signal_check:
      enabled: true
      interval: 30        # SignalCheckJob: le signal files, pausa/aborta canary

# ============================================
# WEBHOOK (GitHub)
# ============================================
webhook:
  enabled: false
  path: /webhook
  secret: ""              # HMAC secret do GitHub

# ============================================
# mTLS (Mutual TLS)
# ============================================
mtls:
  enabled: false
  ca_cert: /opt/runner/certs/ca.pem       # CA certificate do servidor CCS
  server_cert: /opt/runner/certs/server.pem  # Certificado do runner
  server_key: /opt/runner/certs/server.key   # Chave privada do runner

installed_at: "2026-04-16T15:00:00Z"

Campos Detalhados

API

Campo	Tipo	Default	Descricao
`enabled`	bool	`true`	Habilita API HTTP
`port`	integer	`9090`	Porta do servidor
`bind`	string	`127.0.0.1`	Endereco IP de escuta. Para publicar num dominio, use `runner service expose`, que escolhe o bind sozinho. Bind que nao e IP faz a API nao subir (v2.161.0)
`api_key`	string	(gerada)	Chave no formato `rk_{fingerprint}_{random}`. Obrigatoria: vazia ou fora do formato, a API nao sobe (v2.161.0)
`domain`	string	-	Dominio onde a API foi publicada. Escrito pelo `runner service expose` (v2.161.0)

API Key: gerada automaticamente no runner service init. Formato: rk_{SHA256(hostname+MAC+machine-id)[..8]}_{12 random bytes hex}. O prefixo rk_ identifica chaves do runner. O fingerprint (8 chars) e deterministico por servidor — regenerar a key no mesmo servidor produz uma nova key com o mesmo prefixo.

Scheduler

Campo	Tipo	Default	Descricao
`enabled`	bool	`true`	Habilita o scheduler
`tick_interval`	integer	`60`	Segundos entre ticks do loop principal

Scheduler Jobs

Job	Default	Interval	Descricao
`canary`	enabled	tick_interval	Verifica canaries ativos, incrementa peso, health check
`ttl_cleanup`	enabled	300s	Remove PRs/staging expirados por TTL
`signal_check`	enabled	30s	Le signal files, pausa/aborta canary em caso de fail

mTLS

Campo	Tipo	Default	Descricao
`enabled`	bool	`false`	Habilita mutual TLS
`ca_cert`	string	`/opt/runner/certs/ca.pem`	Certificado da CA (do CCS server)
`server_cert`	string	`/opt/runner/certs/server.pem`	Certificado do runner
`server_key`	string	`/opt/runner/certs/server.key`	Chave privada do runner

Quando mTLS esta ativo, o TLS handshake valida o client certificate antes de processar qualquer request HTTP. Conexoes sem certificado valido sao rejeitadas no transport layer.

Hot-reload: o CA cert e relido do disco a cada handshake quando o mtime do arquivo muda. O CCS pode rotacionar o cert via SCP sem restart do runner. Vale desde a v2.161.0; antes, a troca so valia depois de reiniciar.

Arquivo faltando: com enabled: true e sem ca_cert, server_cert ou server_key, a API nao sobe e mostra mtls_incompleto (v2.161.0).

Endpoints da API

Endpoint	Metodo	Auth	Descricao
`/health`	GET	Nenhuma	Health check (`{"status":"healthy","version":"X.Y.Z"}`)
`/api/v1/status`	GET	X-API-Key	Status do scheduler (jobs, run_count, errors)
`/api/v1/signal/{app}`	POST	X-API-Key	Enviar signal externo (status, action, message)
`/api/v1/deploy/{app}`	POST	X-API-Key	Disparar deploy (instance, version, force). 202 `{deploy_id}`; 409 com o lock ocupado (v2.161.0)
`/api/v1/deploy/{id}`	GET	X-API-Key	Status do deploy disparado (v2.161.0)
`/api/v1/apps`	GET	X-API-Key	Listar apps registradas

Autenticacao

Header X-API-Key com o valor do campo api.api_key do service.yml. Comparacao em constant-time para prevenir timing attacks.

curl -H "X-API-Key: rk_a1b2c3d4_e5f6a7b8c9d0e1f2a3b4c5d6" \
     http://localhost:9090/api/v1/status

Systemd Unit

Gerado automaticamente por runner service init:

[Unit]
Description=Runner CI/CD Service
After=network-online.target docker.service

[Service]
Type=simple
ExecStart=/opt/runner/runner serve --service
WorkingDirectory=/opt/runner
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Comandos de Gerenciamento

runner service init [--port N] [--bind ADDR] [--ca-cert PATH] [--no-api]
runner service start | stop | restart | status
runner service config [--port N] [--bind ADDR] [--api-key] [--enable-api] [--ca-cert PATH]
runner service uninstall

By Borlot.com.br on 16/04/2026

# service.yml

# Estrutura Completa

# Campos Detalhados

# API

# Scheduler

# Scheduler Jobs

# mTLS

# Endpoints da API

# Autenticacao

# Systemd Unit

# Comandos de Gerenciamento

Tags