gitdash
Back to blog

GitHub Actions Self-Hosted Runner Updates: Prepare Before Enforcement

Prepare self-hosted GitHub Actions runners for version enforcement, audit your fleet, handle disabled auto-updates, and avoid jobs getting stuck in the queue.

A fleet of CI runner machines with one outdated runner separated by a warning gap and a green upgrade path

Self-hosted runners are easy to forget because a healthy runner can keep doing the same job for months. That is exactly why an old runner can become a release problem. GitHub is resuming minimum-version enforcement for self-hosted runners on GitHub Enterprise Cloud. Brownouts for Enterprise Cloud begin August 24, 2026, and full enforcement is scheduled for September 25, 2026. The official timeline says older runners may stop registering or stop receiving jobs when they fall below the effective version requirement.

What is changing

There are two parts to the requirement. A runner must be on version 2.329.0 or later to configure or register with the new platform. After that, the runner must continue installing new runner releases within 30 days. The registration version is only a floor for joining the platform. It is not a version you can install once and leave untouched. GitHub's runner reference treats major, minor, and patch releases as available updates for the 30-day rule.

  • Registration requirement: 2.329.0 or newer.
  • Runtime requirement: install each new runner release within 30 days.
  • Security exception: job queuing can pause until a critical update is applied.

The August 24 date matters

GitHub Enterprise Cloud has a staged rollout before full enforcement. The first brownout is scheduled for August 24, followed by more registration and runtime brownouts through September. The practical consequence is that a runner may look fine during one check and fail during a later window. Treat the first brownout as an inventory signal, not as the only day you need to act.

GitHub Enterprise Cloud timeline

August 24       First configuration brownout
August 31       Configuration brownout
September 2    Configuration brownout
September 7    Configuration brownout
September 9    Configuration and runtime brownout
September 14   Configuration and runtime brownout
September 16   Configuration and runtime brownout
September 18   Configuration and runtime brownout
September 25   Full enforcement

The exact brownout dates can change, so keep the GitHub changelog open while you work through the upgrade. The dates above are the current Enterprise Cloud schedule, not a promise that every runner will fail on each listed day.

First find the runners you actually own

Do not start by searching workflow YAML for runs-on: self-hosted. That tells you where jobs want to run, not whether the runner is current. Inventory at the repository, organization, and enterprise levels. The runners API includes each registered runner's operating system, status, labels, and version. GitHub's REST API reference is the useful source for building a fleet report.

gh api --paginate \
  /orgs/ORG/actions/runners \
  --jq '.runners[] | [.name, .os, .status, .version, (.labels | map(.name) | join(","))] | @tsv'

This example is illustrative. Replace ORG with an organization you are allowed to inspect and make sure the GitHub CLI is authenticated with permission to list its runners. For a complete fleet, repeat the inventory at each scope you use and include runners managed through an autoscaling controller or image pipeline.

Do not confuse runner updates with host updates

The runner application can update itself, but that does not update the operating system, Docker, language runtimes, caches, or tools installed on the machine. Your upgrade plan needs two tracks: get the Actions runner above the service requirement, then keep the host image and job dependencies supportable.

Runner upgrade inventory

- Runner name and scope
- Current runner version
- Auto-update enabled or disabled
- Host image or container tag
- Operating system and architecture
- Service or controller responsible for restarts
- Workflows and labels that depend on it
- Last successful test job
- Rollback or replacement plan

If auto-update is disabled, own the calendar

Auto-updates are the simplest path when your runner setup can support them. Teams often disable them for container images or tightly controlled hosts, then forget that the 30-day requirement still applies. GitHub's monitoring guidance points to the Runner_ and SelfUpdate logs as evidence that the update process is working.

For pinned container images, make the runner version part of the image update process. Build the new image, run a representative job against it, publish it, and replace old runners before the deadline. Updating only the registration script does not help if the actual runner binary comes from a stale image layer.

Test the upgrade without waiting for production CI

A runner can be online and still be unusable for the workflow you care about. After updating, run a small canary job that exercises the runner's labels, Docker access, network path, toolchain, artifact handling, and any required private services. Keep it separate from a production deployment so a runner check cannot change live state.

name: Runner canary

on:
  workflow_dispatch:

jobs:
  canary:
    runs-on: [self-hosted, linux, x64]
    steps:
      - name: Check runner version
        run: echo "Runner canary is executing on $RUNNER_NAME"
      - name: Check core tools
        run: |
          uname -a
          docker --version
          node --version
      - name: Write a temporary file
        run: echo ok > runner-canary.txt
      - name: Upload canary output
        uses: actions/upload-artifact@v7
        with:
          name: runner-canary
          path: runner-canary.txt

Use the labels and tools that match your real jobs. The point of a canary is not to prove that the runner process started. It is to prove that a representative workflow can start, execute, and finish on the updated environment.

A rollout order that avoids a fleet-wide surprise

  1. Inventory runner versions and locate every disabled auto-update path.
  2. Update the base image, runner package, or autoscaling template used to create new runners.
  3. Run a canary job on the updated runner and inspect its logs.
  4. Replace or rotate the remaining old runners in small batches.
  5. Re-run the inventory and record the owner and next update path for every remaining runner.

If a runner cannot be updated safely, take it out of the critical path and replace it with a fresh runner. Treating a machine as irreplaceable is usually the bigger operational risk than the version update itself.

Do not wait for the queue to tell you

The useful response to runner enforcement is not a last-minute reinstall on the machine that happens to be busy. It is a small operating process: report versions, update images, run a canary, rotate the fleet, and keep an owner on the calendar. The August brownouts make the problem visible soon, but the 30-day rule means runner maintenance remains an ongoing responsibility after this deadline passes.