Introduction

Self-hosted GitHub Actions runners provide customized execution environments for workflows. When a self-hosted runner goes offline -- due to server maintenance, network issues, or process crashes -- any workflow configured to run on that runner (runs-on: self-hosted) cannot execute. Scheduled workflows are particularly vulnerable because they run unattended and failures may go unnoticed for hours.

Symptoms

  • Scheduled workflow shows queued status indefinitely
  • Workflow run fails with No runner online with the requested labels
  • Self-hosted runner shows as Offline in repository Settings > Actions > Runners
  • Runner process is not running on the host machine
  • Error message: This run has no logs because the runner was offline

Common Causes

  • Runner host server rebooted for maintenance or updates
  • Runner process crashed due to OOM or unhandled error
  • Network connectivity loss between the runner and GitHub's servers
  • Runner registration token expired after repository transfer
  • System clock drift on the runner host causing authentication failures

Step-by-Step Fix

  1. 1.Check the runner status in GitHub: Verify the runner is offline.
  2. 2.`
  3. 3.# GitHub UI: Repository > Settings > Actions > Runners
  4. 4.# Check runner status (Online/Offline)
  5. 5.# Or via API
  6. 6.gh api repos/{owner}/{repo}/actions/runners --jq '.runners[] | {name, status}'
  7. 7.`
  8. 8.Check the runner process on the host: Verify if the runner agent is running.
  9. 9.```bash
  10. 10.ps aux | grep run.sh
  11. 11.# Check runner logs
  12. 12.tail -100 /opt/actions-runner/_diag/Runner_*.log
  13. 13.`
  14. 14.Restart the runner agent: Bring the runner back online.
  15. 15.```bash
  16. 16.cd /opt/actions-runner
  17. 17.# If the process has stopped
  18. 18../run.sh &
  19. 19.# Or as a systemd service
  20. 20.systemctl restart actions-runner
  21. 21.`
  22. 22.If the runner needs re-registration: Re-register with a fresh token.
  23. 23.```bash
  24. 24.cd /opt/actions-runner
  25. 25../config.sh remove --token <runner-pat>
  26. 26.# Generate new registration token from GitHub
  27. 27../config.sh --url https://github.com/owner/repo --token <new-token>
  28. 28../run.sh &
  29. 29.`
  30. 30.Configure the runner as a resilient service: Prevent future offline events.
  31. 31.```bash
  32. 32.# Install as systemd service with auto-restart
  33. 33.sudo ./svc.sh install
  34. 34.sudo ./svc.sh start
  35. 35.# Verify service status
  36. 36.sudo ./svc.sh status
  37. 37.`

Prevention

  • Install self-hosted runners as systemd services with Restart=always
  • Configure multiple runners with the same labels for redundancy
  • Monitor runner online status with automated alerts (GitHub API polling)
  • Add fallback runs-on: [self-hosted, ubuntu-latest] for critical workflows
  • Set up runner health checks that verify connectivity to GitHub's API
  • Include runner recovery in incident response runbooks with automated restart scripts