# `runner hook`

Desde a v2.173.0. Gerencia o segredo do webhook de deploy de uma app com source: {type: registry}. O contrato HTTP e o uso com a Action estão em Deploy por imagem de registry.

A rota só existe com o serviço ligado (runner service init --enable-api, depois start).

# `runner hook secret [--rotate | --remove] [--json]`

Cria o segredo da app e o grava num arquivo com modo 600: <state_dir>/hooks/<app>.secret. O segredo também fica cifrado no state. A saída mostra o caminho e a impressão digital (sha256, 12 hex). Nunca o segredo, nem em -o json.

runner hook secret minha-api
sudo tr -d '\n' < /caminho/mostrado | gh secret set RUNNER_HOOK_SECRET --repo minha-org/minha-api

O arquivo é do root (modo 600), por isso o sudo na leitura.

O tr -d '\n' tira a quebra de linha final: a assinatura usa o segredo sem ela. A Action também a remove.

{
  "app": "minha-api",
  "key_file": "/opt/runner/state/hooks/minha-api.secret",
  "key_fingerprint": "6f6df8e68280",
  "endpoint": "/api/v1/hooks/deploy/minha-api",
  "rotated": false
}

O arquivo some junto com a app (runner remove).

# Abrir o hook fora da VPN

runner service expose --domain runner.exemplo.com --vpn-only --hooks-publicos

A flag só faz sentido com --vpn-only (ou com middleware que restrinja a origem): sem ela, a API inteira já é pública e o runner avisa que a flag é redundante. Com --vpn-only, a API fica na VPN e só /api/v1/hooks/ ganha um router próprio, sem esses middlewares.

Para fechar só o hook, rode o expose de novo sem --hooks-publicos. O unexpose tira a rota da API inteira, não só a do hook.

# Assinatura

• X-Runner-Timestamp: segundos Unix, aceito em ±300 s.
• X-Runner-Signature: sha256=<hex>, com HMAC-SHA256(segredo, timestamp + "." + corpo).

A API key global não abre esta rota, e o segredo da app não abre nenhuma outra. O mesmo pedido assinado só é aceito uma vez (anti-replay).