GitHub Actions Runner Version Expired? 2026 Mac Upgrade Checklist

A GitHub announcement on minimum-version enforcement confirms that self-hosted Runner eligibility can be enforced by version, not just by whether the node appears online.

Symptom: Your Mac Runner is online, but jobs are queued, refused, or never start.

Fast fix: Do not wait for task intake to stop. Audit the update path now; create a backup node before upgrading fixed-version systems, and roll out large pools through test, canary, and rollback stages.

Last updated August 26, 2026. Dates and enforcement guidance were checked against GitHub’s minimum-version announcement, the official self-hosted Runner documentation, and the current Runner release page. The account’s own download instruction remains the final source for the version available to your Runner group.

Who should use this Mac Runner upgrade runbook?

This guide is for an individual developer with one long-lived Mac Runner, a small team sharing Xcode, signing, and cache state, or a platform team operating fixed-version, restricted-network, or enterprise node pools.

It is not a first-install tutorial. The focus is acceptance: what to inspect, what evidence to collect, when to stop, and when a separate remote Mac is safer than overwriting a production Mac build node.

Version enforcement changes the meaning of “online”

A registered Runner has several independent states:

• The process can reach GitHub.
• The Runner is registered to the expected repository, organization, or enterprise.
• Labels still route jobs to that node.
• The installed version remains within the accepted range.
• The node can execute the actual workflow, including Xcode, signing, tests, and artifact upload.

Only the first state is represented by a simple Online indicator. The Runner monitoring and troubleshooting documentation is therefore more useful than the dashboard status alone when a job stops arriving.

Before touching the Mac, record the following:

1. The Runner scope: repository, organization, or enterprise.
2. The Runner group and all routing labels.
3. The local Runner version and the version shown in the account interface.
4. Whether automatic updates are enabled.
5. The service account, working directory, and service registration.
6. The Xcode, SDK, signing, cache, and package-manager assumptions used by real workflows.
7. The last successful build and its workflow run identifier.

GitHub has confirmed minimum-version enforcement and staged restrictions for GitHub Enterprise Cloud. It has also published dates for enforcement activity that can change as the rollout develops. Treat the official announcement as the policy source, but use the account-level download instruction and current release page to determine what you should install today. Do not copy a version number from an old search result or internal wiki page.

Choose the response by node ownership

The fastest safe path depends less on the Mac model than on who can approve downtime and how many workflows depend on the node.

A node that cannot be upgraded safely should not be forced through a production maintenance window. Increase isolated Mac capacity, reproduce the minimum build chain, and switch only after the backup passes the same acceptance gates.

Single-node developers need a tested escape route

A single Mac Runner creates a hidden availability dependency. If its service is stopped during an upgrade, every job requiring its labels can remain queued. If its signing environment is damaged, a green unit-test workflow can create false confidence.

Start by exporting or recording recoverable state. Preserve the Runner labels, group assignment, service definition, working directory, tool versions, keychain references, environment variables, and cache paths. Do not export private keys or tokens into a plain-text project file. Store secrets through the approved secret-management process and verify that the service account can access the required signing material after restart.

Then create a fallback in one of two ways:

• Use a temporary hosted capacity path if your workflow and policy allow it.
• Provision an isolated remote Mac and reproduce only the minimum toolchain needed for registration, testing, signing, archiving, and artifact delivery.

For a remote option, review MacDate’s Mac compute node options as an operational alternative to taking your only local node offline. The decision is not about adding an untested duplicate. It is about giving the release pipeline a second place to run while the original node is being changed.

Use this sequence:

1. Disable new production intake or remove the node’s production label without deleting its registration.
2. Capture the current service status and recent job logs.
3. Install or stage the approved Runner release from the account instruction.
4. Restart the Runner service and confirm registration.
5. Run a real repository workflow with the expected labels.
6. Reboot the Mac and repeat the registration and task checks.
7. Restore production routing only after the build artifact and signing result are valid.

The acceptance evidence should include the Runner version, label route, service recovery after reboot, test output, archive or package output, and artifact upload. A process that starts is not enough.

Small teams should canary the shared environment

A shared Mac build node usually carries more state than the workflow YAML reveals. The keychain may contain certificates, caches may hide missing dependencies, and a fixed label may be referenced by release jobs across multiple repositories.

Build an inventory before the upgrade:

• Which repositories use the label?
• Which workflows require a specific Xcode or SDK?
• Which jobs use a login keychain or a non-default signing identity?
• Which caches are performance optimizations, and which are accidental dependencies?
• Which local tools are installed outside the repository?
• Which jobs can run on a canary without affecting a release?

Add or isolate one node with a distinct temporary label. Copy the minimum environment, but do not copy production credentials more broadly than policy permits. Run a low-risk test workflow first. Then run a workflow that exercises dependency installation, tests, archive creation, signing, and artifact upload.

Move repositories in risk order. Start with development and pull-request jobs. Next move scheduled or internal builds. Leave App Store or customer-facing release workflows until the canary has survived a service restart and a complete artifact check.

Keep the old node intact until the new path passes the release workflow. A rollback rehearsal should answer one question: can you redirect a job to the previous known-good node without editing secrets, labels, and workflow files under pressure?

Fixed-version and restricted-network nodes need ownership clarity

Disabling automatic updates does not remove the update obligation. It transfers responsibility to the team operating the node. The same applies when a proxy, firewall, private package mirror, or outbound policy prevents the Runner from reaching its approved source.

Check the update chain in this order:

1. Confirm the account or Runner group’s required version guidance.
2. Confirm that the Mac can reach the approved GitHub endpoints through the intended proxy.
3. Confirm the package source and release identity.
4. Verify the package integrity using the organization’s approved method.
5. Confirm that the service account can read, replace, and execute the Runner files.
6. Restart the service and retain the complete update log.
7. Run registration, routing, and real-build checks.

Use the official Runner release list to identify the release artifact, but do not assume the newest public release is automatically the correct enterprise deployment target. Your account instruction, policy, architecture, and rollout status still matter.

Do not disable TLS verification as a routine fix. If an exception is unavoidable, record the reason, scope, expiry, owner, and restoration step before making the change.

A useful operating rhythm is a recurring review of Runner versions, update failures, proxy logs, package provenance, and service permissions. The interval itself should be chosen by your risk policy; the important part is that the review has an owner and produces evidence. “Automatic updates are off” must never be the final state description.

Enterprise pools require inventory before rollout

For an organization or enterprise, a spreadsheet is too weak if it cannot be reconciled with the live platform. Use the self-hosted Runner REST API documentation to design an inventory process that records scope, Runner group, architecture, labels, status, current version, repository access, and update mode.

Separate nodes into operational classes:

• Short-lived nodes: rebuild from a controlled image or provisioning process instead of performing repeated in-place repairs.
• Long-lived nodes: use a staged package update, service validation, and explicit rollback record.
• Autoscaled nodes: update the image or initialization path, then replace instances rather than patching an unknown proportion of the pool.
• Release-critical nodes: require archive, signing, upload, and restart recovery before they are admitted to production routing.

Use three rollout stages:

1. Test: select a non-critical node and prove registration, task intake, real builds, and service recovery.
2. Canary: update a small production-representative cohort covering the main labels and architectures.
3. Production: expand only after logs show normal task claiming, expected failure rates, and valid artifacts.

Do not use “all nodes are Online” as the promotion signal. Compare the before-and-after Runner versions, queued jobs, task acquisition, workflow failures, signing results, artifact availability, and diagnostic logs. Preserve the change ticket, package reference, operator, timestamps, affected labels, and rollback result.

If your inventory shows that a production Mac cannot be safely interrupted, MacDate’s remote Mac node service can serve as an isolated capacity option while you rebuild or upgrade the existing pool. Keep it outside the production label until it passes your own acceptance gates.

Release owners decide with evidence, not green tests alone

The final decision belongs to the person responsible for shipping, because a development workflow can pass while the release path fails. Require one real Xcode build that reflects production behavior:

• dependency resolution,
• unit and integration tests,
• archive generation,
• signing and provisioning,
• artifact verification,
• upload or delivery,
• Runner service restart and recovery.

Use a simple score to make the decision visible:

A production switch should require full marks in the release-critical areas, not merely a passing test job. If the upgraded node scores poorly on registration or routing, pause and restore the backup. If ordinary tests pass but signing or archive fails, keep release labels on the previous node. If the Runner package is accepted but the Mac toolchain is inconsistent, rebuild the node instead of layering more manual fixes.

FAQ for Runner version incidents

How do you verify a self-hosted Runner’s installed version?

Use the local Runner output and service logs, then compare them with the version displayed in the relevant repository, organization, or enterprise settings. Check the official release page and the account’s download instruction together. The local process can report a version while the node remains unsuitable for a job because its labels, permissions, architecture, or signing environment are wrong.

What is the safe path when automatic Runner updates are disabled?

Treat the node as manually maintained. Confirm network access, package provenance, integrity checks, service-account permissions, and a recovery package before replacing anything. Remove or isolate production routing, install the approved release, restart the service, and execute a real build. If the network path or package source cannot be verified, stop the upgrade and use a tested backup node.

Why does an old Runner stay online but reject work?

The connection state and minimum-version eligibility are different controls. The process may continue heartbeating while GitHub enforces a newer minimum version for task execution. Inspect the official enforcement timeline, Runner diagnostics, workflow labels, group permissions, and job logs. This prevents you from incorrectly changing YAML or reinstalling Xcode when the real issue is Runner eligibility.

What is the rollback method after a failed Mac upgrade?

First stop new intake and move jobs to a validated backup. Preserve logs and the failed package state for diagnosis. Restore the previous package only if it remains accepted by GitHub, then verify service startup, registration, labels, signing, archive creation, and artifact delivery. If the old version is no longer eligible, rebuild the node from a known-good image or use temporary remote capacity.

Current Mac node or isolated remote Mac?

Keeping one production Mac unchanged avoids a migration today, but it leaves you with a single failure domain, an untested recovery path, and growing maintenance pressure when automatic updates are disabled. A self-managed Mac can also accumulate undocumented keychain, cache, proxy, and toolchain dependencies that make a rushed upgrade harder.

An isolated MacDate node does not remove the need for your own security, signing, and acceptance controls. It can, however, give you a separate place to reproduce the minimum GitHub Actions workflow, test the Runner upgrade, and maintain build capacity while the primary Mac is unavailable. That makes temporary capacity or a short migration window more practical than overwriting the only production node.

Start by inventorying your existing Runner and performing one backup-node switch rehearsal. If the production Mac cannot be stopped safely, copy the smallest real build chain to an isolated remote Mac, verify registration, labels, signing, and the actual project, then switch routing only when the evidence supports it.