skip to content

In GitLab, what makes a runner stale rather than offline, and how do you find and clean up stale runners across a fleet?

level: seniorimportance: should knowfreq 16%

answer

  1. last contact with GitLab
  2. two hours versus seven days
  3. threshold shortened in 17.1
  4. group-level automatic cleanup
  5. unregister on the host too

basics

~20 s

A GitLab runner is offline after more than 2 hours without contacting GitLab and stale after more than 7 days (since GitLab 17.1). Spot them in the instance or group runner list, then delete them or, on Ultimate, enable group stale runner cleanup.

solid answer

~50 s

GitLab derives runner status from the last time the runner contacted it: `online` within the last 2 hours, `offline` after more than 2 hours, `stale` after more than 7 days, and also stale if it was created more than 7 days ago but never contacted GitLab. GitLab 17.1 shortened the stale threshold from 3 months to 7 days. The instance runner list in the Admin area and each group's runner list show every runner's status; on Ultimate the runner fleet dashboard adds online and offline counts, usage and job wait time. To clean up, **delete** runners that are gone for good, **pause** ones you only want to stop temporarily, and on Ultimate a group Owner can turn on **Enable stale runner cleanup** so group runners inactive for more than seven days are deleted automatically. Deleting in GitLab does not touch the host, so unregister the runner there too.

go deeper

for a junior

Recall the runner statuses: online within 2 hours of last contact, offline after more than 2 hours, stale after more than 7 days or when a runner older than 7 days never contacted GitLab.

for a middle

Explain where each status is visible, the difference between pausing and deleting a runner, and that GitLab 17.1 shortened the stale threshold from three months to seven days.

for a senior

Show a cleanup routine you have run: filtering lists or the fleet dashboard, bulk deletion with the right role, automatic group stale cleanup on Ultimate, and unregistering on the host so deleted runners stop polling.

for a principal

Treat fleet hygiene as policy: who owns each runner, when cleanup is automatic, how stale registrations count as credential exposure, and which metrics prove capacity matches the queue.

## How GitLab decides a runner's status A registered runner keeps **contacting GitLab** to ask for jobs. GitLab records the time of the last contact and derives the status from it: | Status | Meaning | |---|---| | `online` | Contacted GitLab in the last 2 hours; available to run jobs | | `offline` | Has not contacted GitLab for more than 2 hours; not available | | `stale` | Has not contacted GitLab for more than 7 days, or was created more than 7 days ago and never contacted it | | `never_contacted` | Has never contacted GitLab | So **offline** is a short-term state (the host is down, restarting, or lost its network), while **stale** is the long-term signal that the runner is probably abandoned: a decommissioned VM, a laptop someone registered once, or a host rebuilt without its old registration. GitLab **17.1** changed the stale timeout from **3 months to 7 days**. Older runbooks and scripts that assumed a quarter of silence before a runner counts as stale now see far more stale runners, far sooner. ## Finding stale runners - **Runner lists.** An administrator sees all instance runners in the **Admin** area under CI/CD > Runners; a group's runners appear under the group's **Build > Runners**. Both lists show each runner's status and can be searched and filtered. - **Runner fleet dashboard (Ultimate).** The administrator's view covers the instance on GitLab Self-Managed; the group view, available on GitLab.com and Self-Managed as a beta, needs the Maintainer role on the group. It shows **Online**, **Offline** and **Active runners** counts, **Runner usage (previous month)** in compute minutes with a CSV export, and **Wait time to pick a job**. On Self-Managed the last two need the ClickHouse integration. - **Upgrade status (Ultimate).** The same lists flag runners as **Outdated - recommended** or **Outdated - available**, which helps decide whether an old but online runner should be replaced. For a team on GitLab.com with a few dozen of its own runners, the runners sit at group or project level, so the group's runner list and the group fleet dashboard are the places to look. ## Cleaning up 1. **Decide between pause and delete.** A **paused** runner stops accepting jobs but keeps its registration, so it can be resumed. **Deleting** removes it from the GitLab instance permanently. 2. **Delete in bulk where you can.** Instance and group runner lists let you select several runners and choose **Delete selected**. Deleting an instance runner needs an administrator; a project runner needs a project Maintainer or an administrator, and a project runner enabled in more than one project must first be disabled in the others. 3. **Automate group cleanup (Ultimate).** A group **Owner** can turn on **Enable stale runner cleanup** in the group's CI/CD settings. GitLab then deletes the group's runners that have been inactive for more than seven days, and logs how many it removed. It applies to group runners only; project runners still need deleting by hand. 4. **Unregister on the host.** Deleting a runner in GitLab does not edit the host. If the host still holds the deleted runner's configuration it keeps contacting GitLab, so unregister the runner there as well, using the runner's own command line. ## What GitLab already cleans up for you GitLab periodically deletes **stale runner managers**, the per-connection records it keeps under a runner, to keep its database lean; if that host contacts GitLab again the record is recreated. This is housekeeping, not a substitute for removing stale **runners**, which stay listed until someone deletes them or group cleanup does. On the administrator's dashboard, the **Offline** count leaves out runners that were registered but never connected, so a fleet full of abandoned registrations can look healthier there than in the runner list. Compare the dashboard's counts with the list before deciding the fleet is clean. ## Why it matters - Stale entries hide the real capacity of the fleet: thirty registered runners with twelve stale means jobs queue on eighteen. - Each registration is an entry someone has to account for in audits; deleting the ones nobody runs keeps the list an honest inventory of what the team operates. - Accurate online and offline counts make the dashboard's wait-time metric meaningful when jobs start waiting for a runner.

  • In GitLab, a runner was registered ten days ago but its host was never started. What status does it have?
    It counts as stale even though it has also never contacted GitLab: the docs treat a runner created more than 7 days ago that never contacted the instance as stale, as well as one silent for more than 7 days. Starting the runner process on the host would bring it online; otherwise delete it.
  • In GitLab, what does a group Owner need before turning on Enable stale runner cleanup, and what does it miss?
    The group must be on Ultimate and the person needs the Owner role. Once on, it deletes the group's runners inactive for more than seven days; it does not touch project runners, and it does not unregister anything on the hosts.

  • Offline and stale mean the same thing in GitLab.
  • A runner becomes stale only after three months of silence in current GitLab.
  • Deleting a runner in GitLab also stops the runner process on its host.
  • Enable stale runner cleanup also removes stale project runners.
  • Pausing a runner deletes its registration.

Assumes GitLab 19.4; since GitLab 17.1 a runner is stale after more than 7 days without contact instead of 3 months.