Self-hosted runner shows Offline

A GitHub self-hosted runner shows Offline when GitHub has not heard from it for a while. Check four things in order: the runner service, sleep, the network, and whether the runner was removed.

The short answer

A self hosted runner offline in GitHub almost always has one of four causes. The service stopped. The machine slept. The network blocks GitHub. Or the runner was removed. Work through the checks below in order.

What Offline means in GitHub

A runner keeps a line open to GitHub, asking for jobs. When GitHub stops hearing from it, the runner shows Offline. You see it in Settings › Actions › Runners. Jobs that need it wait as Queued. If a runner drops off mid-job, GitHub marks the job as lost and it fails. GitHub also removes runners that stay offline a long time. Check GitHub's docs for the current rule.

Check 1: is the runner service running?

Go to the runner's folder and check its service:

cd ~/actions-runner
sudo ./svc.sh status   # Linux
./svc.sh status        # macOS

If it stopped, start it with sudo ./svc.sh start (on macOS, no sudo). If it keeps stopping, read the newest log in the _diag folder.

On Linux, the service is a systemd unit. List it with:

systemctl list-units 'actions.runner.*'

Check 2: did the machine sleep?

A sleeping machine can't reach GitHub. Laptops sleep when the lid shuts on battery. On a Mac, see what keeps it awake, and stop sleep on power:

pmset -g assertions
sudo pmset -c sleep 0

On Linux, turn off suspend:

sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

Check 3: network and proxy

The runner needs outbound HTTPS on port 443 to GitHub. Test it from the machine:

curl -sI https://api.github.com | head -1

Behind a proxy? Put https_proxy=http://proxy:8080 in the .env file in the runner's folder. Then restart the service.

Check 4: removed or expired runner

If the runner was removed on GitHub, the service can't get back in. Its log says so. Register it again with a new token from Settings › Actions › Runners › New self-hosted runner:

./config.sh remove --token OLD_OR_NEW_TOKEN
./config.sh --url https://github.com/OWNER/REPO --token NEW_TOKEN
sudo ./svc.sh install && sudo ./svc.sh start

How Codemany avoids it

With Codemany, a GitHub Actions runner offline for long is rare. Each job gets a fresh just-in-time runner, so no old runner sits idle and drops off. A crashed runner is replaced, backing off from 5 seconds up to 5 minutes. A runner offline for 2 minutes is stopped and replaced.

Codemany keeps the Mac awake while jobs run, until 2 minutes after the last job. On Linux it blocks sleep the same way. If the Mac slept anyway, the app tells you which jobs were lost. If GitHub disconnects, Codemany retries every 5 minutes. Updates install themselves after running jobs finish. Codemany Console shows all your machines in one tab. To check one machine, run codemany doctor. More fixes are in Troubleshooting.

Questions

Why does my runner go offline when my Mac sleeps?

A sleeping Mac cannot reach GitHub. Codemany keeps the Mac awake while jobs run.

Does a runner come back by itself?

The service retries, but a removed runner must be registered again.

How do I know a machine is offline?

Codemany Console shows all your machines in one browser tab. On the machine, run codemany doctor to see what is wrong.

Start a 14-day trial $20 a month for 2 machines. No card needed.