actions-runner-controller/controllers/actions.github.com
Rob Howie ff7b81dc8f fix: add health check to detect and recover stale EphemeralRunner registrations
fix: add health check to detect and recover stale EphemeralRunner registrations

## Summary

Adds a GitHub-side registration health check to the `EphemeralRunnerReconciler`. During reconciliation of a running EphemeralRunner that has a valid `RunnerId`, the controller now calls `GetRunner()` against the GitHub Actions API to verify the registration still exists. If the API returns 404 (registration gone), the runner is marked as failed so the `EphemeralRunnerSet` can provision a replacement.

This also fixes `deleteRunnerFromService` to tolerate 404 from `RemoveRunner`, since a runner whose registration was already invalidated will also 404 on removal. Previously this caused `markAsFailed` to error and trigger a requeue loop, preventing cleanup of stale runners.

A redundant pod phase check was removed from the health check path — `checkRunnerRegistration` is only called from within the `cs.State.Terminated == nil` branch (container confirmed running), so the phase check was unnecessary and could cause false negatives since the local `EphemeralRunner` object may not have the updated phase yet.

## Changes

- **`ephemeralrunner_controller.go`**: New `checkRunnerRegistration()` method that calls `GetRunner()` and returns unhealthy only on confirmed 404. Transient API errors (500, timeouts, etc.) are logged and ignored to avoid false positives. Called during reconciliation when a running pod has a non-zero `RunnerId`.
- **`ephemeralrunner_controller.go`**: `deleteRunnerFromService()` now treats 404 from `RemoveRunner` as success, since the runner is already gone.
- **`ephemeralrunner_controller_test.go`**: Two new test cases — one verifying a 404 from `GetRunner` marks the runner as failed, another verifying a 500 does not. Both simulate a running pod container status before the health check triggers.
- **`fake/client.go`**: New `WithRemoveRunnerError` option for the fake client to support testing the 404 removal path.

## Issues Fixed

### Directly fixes

- **#4396** — *ARC runners did not recover automatically after GitHub Outage*: Runners that lost their GitHub-side registration during the [2026-03-05 GitHub Actions incident](https://www.githubstatus.com/incidents/g9j4tmfqdd09) remained stuck indefinitely because the `EphemeralRunnerReconciler` never verified registration validity. This change adds exactly that verification — on each reconciliation of a running runner, `GetRunner()` confirms the registration exists. If it returns 404, the runner is marked failed and replaced.

- **#4395** — *GHA Self-hosted runner pods are running but the runner status is showing offline*: Runner pods were running for 5-7+ hours showing "Listening for Jobs" but marked offline in GitHub. The pods' registrations were invalidated server-side (same incident), but the controller had no mechanism to detect this. The new health check detects the 404 and triggers cleanup, preventing these zombie runners from accumulating.

### Partially addresses

- **#4397** — *Stale TotalAssignedJobs causes permanent over-provisioning after platform incidents*: This issue has two components: (1) zombie runner pods occupying slots, and (2) the listener's `TotalAssignedJobs` remaining inflated. This PR fixes component (1) — by detecting and cleaning up runners with invalidated registrations, the controller stops accumulating zombie pods. However, the listener-side `TotalAssignedJobs` inflation (a separate code path in `listener.go` → `worker.go`) is not addressed by this change and still requires either a session reconnect mechanism or CR deletion to clear.

- **#4307** — *Ephemeral Runners seem to get stuck when job is canceled or interrupted*: Reports runners getting stuck with `Registration <uuid> was not found` errors in BrokerServer backoff loops after job cancellation. The health check would detect that the registration is gone (404 from `GetRunner`) and mark these runners as failed rather than leaving them in an infinite backoff loop.

- **#4155** — *EphemeralRunner and its pods left stuck Running after runner OOMKill*: Runners that are OOMKilled can end up in a state where the pod is technically running but the runner process is non-functional, and the registration may become stale. The health check provides a secondary detection mechanism — if the GitHub-side registration is invalidated for a non-functional runner, it will be caught and cleaned up.

- **#3821** — *AutoscalingRunnerSet gets stuck thinking runners exist when they do not*: Reports the AutoscalingRunnerSet believing runners exist when no pods are present, requiring CR deletion to recover. While the root cause may vary, stale registrations that the controller cannot clean up (due to `RemoveRunner` 404 errors causing requeue loops) are one contributing factor. The 404 tolerance in `deleteRunnerFromService` directly addresses this cleanup path.

## Test Plan

- [x] Unit test: `GetRunner` returning 404 → runner marked as failed
- [x] Unit test: `GetRunner` returning 500 → runner NOT marked as failed (transient error tolerance)
- [x] Unit test: `RemoveRunner` returning 404 → deletion succeeds (runner already gone)
- [ ] Integration: Deploy to a test cluster, manually delete a runner's registration via the GitHub API, verify the controller detects and replaces it
- [ ] Integration: Simulate incident conditions by blocking `broker.actions.githubusercontent.com` for running runners, then unblocking — verify stale runners are detected and replaced
2026-03-09 09:31:17 +00:00
..
metrics Provide scale-set listener metrics (#2559) 2023-08-21 13:50:07 +02:00
autoscalinglistener_controller.go Restart the listener if pod is evicted (#4332) 2025-12-09 17:55:09 +01:00
autoscalinglistener_controller_test.go Restart the listener if pod is evicted (#4332) 2025-12-09 17:55:09 +01:00
autoscalingrunnerset_controller.go Code style changes on the controller (#4324) 2025-11-21 14:20:44 +01:00
autoscalingrunnerset_controller_test.go Code style changes on the controller (#4324) 2025-11-21 14:20:44 +01:00
clientutil.go chore(deps): bump sigs.k8s.io/controller-runtime from 0.13.1 to 0.14.1 (#2132) 2023-01-27 09:23:28 +09:00
constants.go feat: add default linux nodeSelector to listener pod (#4377) 2026-02-24 17:56:39 +01:00
ephemeralrunner_controller.go fix: add health check to detect and recover stale EphemeralRunner registrations 2026-03-09 09:31:17 +00:00
ephemeralrunner_controller_test.go fix: add health check to detect and recover stale EphemeralRunner registrations 2026-03-09 09:31:17 +00:00
ephemeralrunnerset_controller.go Remove ephemeral runner when exit code != 0 and is patched with the job (#4239) 2025-09-17 21:40:37 +02:00
ephemeralrunnerset_controller_test.go Add ephemeral runner finalizer during creation and check finalizer without requeue (#4320) 2025-11-20 23:06:27 +01:00
error.go Remove JIT config from ephemeral runner status field (#4191) 2025-08-04 12:35:04 +02:00
helpers_test.go Code style changes on the controller (#4324) 2025-11-21 14:20:44 +01:00
indexer.go Extract single place to set up indexers (#3454) 2024-05-17 14:42:46 +02:00
options.go Make EphemeralRunnerController MaxConcurrentReconciles configurable (#3832) 2024-12-11 21:19:43 +01:00
resourcebuilder.go feat: add default linux nodeSelector to listener pod (#4377) 2026-02-24 17:56:39 +01:00
resourcebuilder_test.go feat: add default linux nodeSelector to listener pod (#4377) 2026-02-24 17:56:39 +01:00
secret_resolver.go Azure Key Vault integration to resolve secrets (#4090) 2025-06-11 15:53:33 +02:00
suite_test.go Create backoff mechanism for failed runners and allow re-creation of failed ephemeral runners (#4059) 2025-05-14 15:38:50 +02:00
utils.go Introduce new preview auto-scaling mode for ARC. (#2153) 2023-01-17 12:06:20 -05:00
utils_test.go Introduce new preview auto-scaling mode for ARC. (#2153) 2023-01-17 12:06:20 -05:00