Skip to content

Komodo push-to-deploy (GitHub Actions relay)

How pushes to main trigger Komodo deploy-infra without public ingress to komodo.infra.realemail.app.

Why not a GitHub repo webhook?

*.infra.realemail.app resolves only on the LAN (AdGuard rewrites → 192.168.6.17). GitHub's webhook delivery IPs cannot reach Komodo directly — deliveries failed with 502 "failed to connect to host".

Komodo still polls the repo every 5 minutes; the relay gives immediate deploy on merge.

Architecture

sequenceDiagram
  participant GH as GitHub (push to main)
  participant WF as Actions (self-hosted runner)
  participant K as Komodo listener
  participant P as deploy-infra Procedure

  GH->>WF: komodo-deploy.yml
  WF->>WF: Sign payload (KOMODO_WEBHOOK_SECRET)
  WF->>K: POST /listener/github/procedure/deploy-infra/main
  K->>P: RunProcedure (PullRepo + BatchDeployStackIfChanged)
Piece Location
Workflow .github/workflows/komodo-deploy.yml
Trigger script scripts/trigger-komodo-deploy.py
Procedure services/komodo/resources.toml — deploy-infra
Runner [self-hosted, Linux, X64, homelab-lan] on infra-services (/home/someone/actions-runner, systemd)
Secret GitHub repo secret KOMODO_WEBHOOK_SECRET (must match host compose.env)

Docs-only pushes are excluded via paths-ignore so mkdocs edits do not redeploy stacks.

Self-hosted runner (infra-services)

The repo had zero registered runners until 2026-06-26. The relay requires a runner on the homelab LAN so it can resolve komodo.infra.realemail.app.

Item Value
Host infra-services (192.168.6.17)
Path /home/someone/actions-runner
Service actions.runner.notarealemail-homelab.infra-services.service
Labels homelab-lan only

Check: sudo systemctl status actions.runner.notarealemail-homelab.infra-services. Re-register after DR: GitHub self-hosted runners / GitHub runner docs. Also used by proxmox-scan.yml and network-scan.yml.

One-time setup (done 2026-06-26)

  1. Set GitHub secret from host:
ssh infra-services 'grep ^KOMODO_WEBHOOK_SECRET= /opt/homelab/services/komodo/compose.env | cut -d= -f2-' \
  | gh secret set KOMODO_WEBHOOK_SECRET --repo notarealemail/homelab

  1. Remove any broken Settings → Webhooks entry pointing at https://komodo.infra.realemail.app/listener/... (GitHub cloud cannot reach it).

  2. Merge workflow + script to main; confirm green Komodo deploy run.

Manual trigger

# From a machine on LAN with infra DNS (or self-hosted runner)
export KOMODO_WEBHOOK_SECRET='…'   # from host compose.env
python scripts/trigger-komodo-deploy.py

Or: Actions → Komodo deploy (push to main) → Run workflow.

Verify

  1. Actions → Komodo deploy — step prints Komodo webhook OK: HTTP 200.
  2. Komodo UI → Procedures → deploy-infra — recent execution after push.
  3. Changed stacks redeploy; unchanged stacks skip (BatchDeployStackIfChanged).

Troubleshooting

Symptom Check
HTTP 401 from listener KOMODO_WEBHOOK_SECRET mismatch between GitHub secret and host compose.env
Connection refused / DNS Runner not on homelab network, or AdGuard rewrite missing for komodo.infra.realemail.app
Workflow skipped Push only touched paths-ignore paths (docs, README, grafana dashboards)
Procedure runs but pull fails Periphery mount /opt/homelab — services/komodo/README.md