How to Monitor Self-Hosted Runner Health in GitHub Actions

A runner that silently goes offline or fills its disk stalls every queued job, so health monitoring is what keeps a self-hosted fleet usable.

Poll the runners REST API for status and busy, export host metrics (disk, memory, load), and alert when runners go offline or a queue builds. The runner also writes diagnostic logs under _diag.

Steps

• Poll the API for each runner status (online vs offline) and busy state.
• Export host disk and memory metrics to your monitoring system.
• Alert when no runner is online for a required label.
• Check the _diag logs on the runner for listener errors.

List runner status

curl -s -H "Authorization: Bearer $GH_TOKEN" \
  https://api.github.com/repos/my-org/my-repo/actions/runners \
  | jq '.runners[] | {name, status, busy}'

Gotchas

• Offline runners do not auto-recover; a watchdog or service restart is needed.
• Disk-full is the most common self-hosted failure; alert on free space before it hits zero.
• Latchkey managed runners self-heal transient failures and auto-replace unhealthy hosts, removing most of this monitoring burden.

Related guides