What If Your GitHub Actions Self-Hosted Mac Runner Version Is Outdated? 2026 Fix Guide

The first decision is whether a node must register, re-register, or simply continue handling jobs. Those are not interchangeable states, and treating one version number as the answer to all three can leave a fleet either unnecessarily disrupted or out of compliance.

For GitHub Enterprise Cloud, the official announcement says that a Runner below 2.329.0 cannot register or register again once enforcement applies. The announcement also says that GitHub Enterprise Cloud with data residency entered enforcement on July 31, 2026. GitHub Enterprise Server is not affected by this announcement. Check the official enforcement notice against the product and deployment model in use.

Runtime support is a separate, moving threshold. GitHub’s current documentation and Runner version retirement REST API are the sources to consult for a specific version’s current status. Do not assume that a node can execute workflows indefinitely because it registered before enforcement or still appears online.

Keep these states distinct in incident notes:

• Registration eligible: The version meets the registration requirement for the applicable GitHub product.
• Runtime supported: The version has not passed the current job-execution retirement threshold.
• Online: GitHub can see the Runner’s connection. This alone does not prove it can accept or finish a workflow.
• Workload verified: A representative workflow has been scheduled and completed successfully on that node or pool.

A useful operational rule follows: decide whether the failure is about registration, runtime support, or actual workflow execution before changing the Mac image or rebuilding the node.

Before upgrading, build an inventory that shows what exists and what each Runner is used for. A list of online nodes is not enough. A Mac used for release signing has different recovery requirements from a disposable test runner, even when both report the same software version.

Collect the inventory across repository, organization, and enterprise scopes where applicable. GitHub’s self-hosted Runner management guide covers Runner administration, while its self-hosted Runner documentation explains update behavior and maintenance responsibilities.

For each node, record:

• Runner version and operating status.
• Whether it is idle or currently running a job.
• Registration scope and the workflow pool or labels that route work to it.
• Whether automatic updates are enabled.
• How the node is created: manually installed, rebuilt from an image, provisioned by deployment automation, or supplied through a container-based workflow.
• Its role in iOS CI/CD, including simulator testing, signing, release packaging, or other production work.
• The owner responsible for updating the Runner and the source image or installation configuration.

Then look up each installed version in the retirement API and attach the result to the matching asset record. Save the lookup date as well as the result. A retirement check is a time-specific fact, not a permanent approval: runtime support changes as new Runner versions arrive.

Pay special attention to nodes that look healthy but are not ready for the next registration event. A node may still be connected while its version is no longer suitable for new registration, while a replacement created from an old image may fail to join the pool. Conversely, a Runner that meets the registration threshold may still need an update to remain supported for executing workflows.

Check the update path too. Automatic updating is useful only if the node can reach the required update service and complete the update. A firewall rule, proxy policy, or network route can make “automatic” a configuration setting rather than a working maintenance process. For nodes with automatic updates disabled, GitHub’s Runner documentation should inform the manual maintenance plan.

Use a staged path rather than updating every Mac at once. That gives the team an early signal if the Runner update, image change, or workflow environment introduces a regression, while leaving a known-good portion of the pool available during investigation.

1. Choose a canary. Select a non-critical Mac that represents the installation method and workflow type used in the pool. Avoid making the only release-signing node the first test.
2. Confirm the target version’s status. Check the current retirement API and official documentation immediately before the change. Record the installed version, target version, and the reason for upgrading.
3. Update the source of truth. For manually maintained nodes, document the manual update and rollback procedure. For image-based or automated provisioning, update the image, install script, template, or other configuration that installs the Runner. If a container image is involved, verify that it will not recreate an older Runner.
4. Upgrade the canary and inspect its behavior. Confirm that the node registers at the intended scope, receives the expected labels, and is available to the intended workflow. Do not infer success from a successful installation alone.
5. Expand by pool, then retain recovery evidence. Upgrade the remaining nodes in manageable groups. Record failures, workflow results, and any changes made to toolchain or signing configuration so the team can determine whether a problem follows the Runner update or another change.

Before each rollout group, verify that there is a practical route back: a known-good image or installation artifact, a way to prevent the old version from being redeployed, and an owner authorized to pause the rollout. A rollback should restore a known-good, supported configuration; it should not simply restore a version that cannot register or is already retired for job execution.

If automatic updates are enabled, verify that they actually work on the canary and that the team knows how to detect a failed update. If updates are disabled, set an explicit maintenance owner and a recurring review of version status. In both cases, update the provisioning source; otherwise replacement Macs can silently undo the fleet upgrade.

The acceptance test must exercise the actual reason the Runner exists. An idle node, a successful install command, or a green status indicator does not establish that the team’s build pool is healthy.

Start with a workflow routed to the upgraded node using the intended labels and scope. Confirm that the Runner accepts the job, starts it, and completes it. Then check the task-specific environment: required Xcode and command-line tools, repository access, dependency resolution, simulator or test behavior where applicable, and expected output artifacts. A successful test on a generic workflow cannot stand in for a release pipeline that has different credentials or signing requirements.

For signing or publishing workflows, validate the complete authorized path separately. Confirm that the job can access only the required credentials, that signing and publishing permissions remain correct, and that the end-to-end task produces the expected release result. Avoid broadening permissions simply to make a canary pass; investigate the specific missing access or configuration instead.

Use this comparison table to decide what evidence is sufficient for each node state:

For broader incident diagnosis, use GitHub’s monitoring and troubleshooting guide. Capture the Runner version, node identity, workflow run, relevant logs, and the time of the retirement check. This lets the next operator distinguish a version rejection from a network, routing, toolchain, or permissions problem.

Can an outdated self-hosted Mac Runner stop accepting or running jobs?

Yes, but registration and execution are governed separately. Under the GitHub Enterprise Cloud policy in the announcement, a Runner below 2.329.0 cannot register or register again after enforcement applies. Runtime support follows a changing threshold. Check the version retirement API for the affected version, and do not use an online indicator as proof that the node can run jobs.

Is Runner 2.329.0 the shared minimum for registration and workflow execution?

No. The announced 2.329.0 threshold concerns registration and re-registration; it is not a permanent minimum for executing workflows. Runtime support advances over time, so a node at that version may still need maintenance later. Check the current API status and test the real workflow rather than treating one historical threshold as a lasting fleet policy.

How should a team maintain Runners after disabling automatic updates?

Assign manual maintenance ownership and track versions in the fleet inventory. Check retirement status on a recurring basis, test an upgrade on a canary, then update the rest of the pool in stages. Also change the image or provisioning automation that installs the Runner. Without that source update, a replacement node can bring the retired version back.

How can administrators find a Runner version’s retirement date?

Use the official self-hosted Runner version retirement REST API and check the entry for the installed version. Record the lookup with the corresponding asset and recheck before an upgrade or recovery action. The result should be interpreted alongside the product scope and whether the question concerns registration or workflow execution; those are distinct policy checks.

A one-time upgrade clears only the current backlog. Add version status to the regular Runner maintenance process so the team can act before a node becomes unable to register or run supported work.

Set up a recurring check that reads the official API and joins its results to the fleet inventory. Generate an alert when a node’s version approaches its applicable retirement state, when an update fails, or when a node remains online but cannot take a representative job. The alert should identify the node owner, its workflow role, the relevant version, and the date of the latest status lookup.

Define a response path for the main failure modes:

• Automatic update fails: Check update-service reachability and local update logs; assign a maintainer if the node needs manual intervention.
• A replacement cannot register: Inspect the installed Runner version and the provisioning source before retrying registration.
• Jobs remain queued: Check labels, scope, capacity, and Runner availability before attributing the queue to version enforcement.
• A job starts but fails: Compare the failure against the validated toolchain, credentials, and workflow result from the canary.
• Rollback is considered: Confirm that the restored Runner version remains eligible and supported for the intended task.

Keep the evidence with the asset record: API lookup, upgrade change, canary result, representative workflow run, and any rollback decision. GitHub’s monitoring and troubleshooting guidance can support the diagnostic process, but the team still needs a clear owner and a defined acceptance result for its own iOS CI/CD workload.

During a fleet upgrade, an existing Mac pool can provide control but also carries real costs: hardware procurement and replacement planning, ongoing maintenance, and uneven versions when machines depend on different images or manual updates. Renting remote Mac capacity can be a better fit when the requirement is temporary build headroom or a test node during a staged migration, because it avoids buying machines solely for a short-lived capacity gap. It is not automatically the right choice for a consistently busy fleet or workloads that require locally attached hardware; those should be assessed against the team’s access, security, and operational requirements.

For teams evaluating temporary capacity, NUKCLOUD remote Mac options can be considered alongside the existing fleet after Runner version checks and workflow acceptance are in place. Teams that have identified a temporary build-capacity need can also review NUKCLOUD’s Mac rental options when assessing whether an additional remote node fits the migration window. Treat it as an elastic migration or peak-capacity option, not as a substitute for checking version retirement or validating the actual Mac CI workload.