Introduction

Self-hosted runners are reliable only if the runner process, the host machine, and outbound connectivity to GitHub all stay healthy. When that chain breaks, the runner goes offline and workflows pile up in queue. The goal is to determine whether the runner process died, the machine ran out of resources, or the host can no longer maintain its connection to GitHub.

Symptoms

  • GitHub shows the runner as offline
  • Jobs remain queued waiting for a self-hosted runner
  • The runner host is reachable, but no jobs are picked up
  • The problem started after a reboot, disk growth, package update, or network change

Common Causes

  • The runner service stopped or crashed
  • The host lost outbound connectivity to GitHub
  • Disk or memory exhaustion killed the runner process
  • The runner was updated, moved, or partially reconfigured without a clean restart

Step-by-Step Fix

  1. 1.Check whether the runner service is actually running
  2. 2.On most stable installations the runner should be managed by systemd or another service manager, not a manually started terminal session.
bash
sudo systemctl status actions.runner
  1. 1.Inspect runner diagnostic logs
  2. 2.The _diag logs usually show whether the problem is connectivity, process failure, or repeated update errors.
bash
tail -100 /opt/actions-runner/_diag/Runner_*.log
  1. 1.Check host resource pressure and outbound connectivity
  2. 2.A full disk, low memory, or blocked outbound HTTPS path can all make a runner appear randomly offline.
bash
df -h
free -h
curl -I https://github.com
  1. 1.Restart cleanly and reconfigure only if the installation is actually broken
  2. 2.Most incidents are solved by restoring service health. Full re-registration is a last step when the runner installation itself is damaged or intentionally replaced.
bash
sudo systemctl restart actions.runner

Prevention

  • Run self-hosted runners as managed services with automatic restart
  • Alert on runner offline state and queued job buildup
  • Keep enough disk and memory headroom for build spikes
  • Test outbound connectivity to GitHub after firewall, proxy, or network policy changes