Apple Declarative Software Updates For macOS 27 Golden Gate

The console says the update command was sent, but a macOS 27 node does nothing.

Move to Apple Declarative Software Updates For macOS 27 Golden Gate before production release. Apple says legacy software update commands, queries, recommended cadence settings, and traditional deferrals no longer function across all 27.0 operating systems. Validate declarations, status reporting, authorization, restart recovery, and CI re-entry on non-critical nodes first. (Apple’s macOS 27 device management update)

This guide is for IT administrators still pushing updates through old MDM workflows, platform engineers managing remote Mac and CI Runner fleets, and operations leads running macOS 26 and macOS 27 side by side.

Last updated August 9, 2026. Technical details were checked against Apple’s WWDC26 device management update, macOS 27 beta documentation, declarative software update documentation, and Apple’s software update lookup guidance. macOS 27 beta 4 was released on July 20, 2026 as build 26A5388g. Apple has not confirmed the final release date or final production build.

The old command path looks healthy until macOS 27 takes control away

A common failure pattern looks like this:

• Your MDM console creates a software update command.
• The device checks in.
• The command appears as sent or acknowledged.
• The Mac remains on its current system version.
• A query or compliance report still shows an old state.
• The node misses its maintenance window and continues accepting production work.

The hidden problem is not always APNs, enrollment, or network access. The device may be reachable while the software update mechanism you depend on is no longer authoritative.

Apple’s macOS 27 device management update explicitly lists the affected legacy areas:

• Software update commands.
• Software update queries.
• Recommended cadence settings.
• Software update restrictions, including deferrals and Background Security Improvements.

Apple’s stated replacement is declarative software update management. That changes the control model. Instead of repeatedly asking the device to perform an action, your management service publishes the desired configuration. The Mac evaluates the active declarations and reports state as it moves through the update process.

Do not wait for the macOS 27 production release to begin migration. Your minimum readiness gate is a non-critical device that can receive a software update declaration, report activation, identify the target release, complete authorization and restart, and return to service.

Three operational costs make late migration risky:

1. False success in the console. A command delivery event does not prove that the update was accepted, prepared, installed, or completed. Apple’s MDM guidance says a command should not be treated as executed until the matching device response is received. Declarative management adds a second requirement: track the declaration and status items rather than only the original command record.

2. Mixed control planes. A macOS 26 node may still respond to legacy workflows while a macOS 27 node follows the new behavior. One fleet-wide compliance rule can therefore report “healthy” while applying the wrong mechanism to part of the fleet.

3. Restart and workload risk. A Mac can install the correct system version and still fail its operational objective if remote access does not return, the agent does not reconnect, or the CI Runner accepts work before its toolchain is ready.

The migration target is not simply “the version changed.” It is a complete operational loop:

declaration active → target available → update prepared → installation enforced → restart completed → device reports again → CI or remote workload restored

Legacy MDM versus declarations: map each control to a new source of truth

Start by exporting every workflow that touches macOS software updates. Do not limit the inventory to commands named ScheduleOSUpdate. Include scripts, compliance jobs, dashboards, profile payloads, and approval logic that may hide update assumptions.

For each workflow, classify the old capability:

• On-demand update command: replace the action with a software update enforcement declaration.
• Available-version query: use Apple’s Software Lookup Service to determine what Apple makes available for the device model and channel, then use device status to confirm what the Mac has received and processed.
• Recommended cadence: replace it with an explicit update offer or deferral policy.
• Traditional deferral profile: move the policy into SoftwareUpdateSettings declarations.
• Post-command compliance check: subscribe to declarative status items and record the installation reason and current phase.
• Approval workflow: retain it if useful, but make the approval change the declaration or its target date. Do not leave the old command as the enforcement mechanism.

Apple documents that declarative software update management can target an operating system version or build. The TargetBuildVersion key can also identify a specific build, including a supplemental version identifier. This distinction matters when your CI toolchain requires a particular build rather than merely “macOS 27.” (Apple’s declarative software update documentation)

Use the Apple field-level documentation when defining declarations. Use the Software Lookup Service to separate “Apple offers this release to the device” from “the device has installed this release.” These are different control points and should not share one compliance field.

What should remain in the old approval process? Human approval, maintenance-window scheduling, change tickets, incident escalation, and business freeze dates can remain. The part that must change is the device-side update control and its evidence.

Your migration evidence should contain at least these signals:

• The declaration is active on the intended device.
• The target operating system or build is available.
• The device reports waiting, downloading, prepared, installing, failed, or none as appropriate.
• The installation reason identifies declarative enforcement when that is the intended path.
• The Mac checks in after restart.
• The remote agent or CI Runner reconnects only after its health checks pass.

Apple’s documented status sequence includes waiting, downloading, prepared, installing, failed, and none. The status model also distinguishes a declaration-triggered installation from an MDM command, automatic update, notification, or command-line installation.

Three rollout policies: hold, offer, or enforce

Teams often try to carry their old deferral logic into macOS 27 without changing the decision model. That creates ambiguous states. A node may be hidden from users, unavailable to automation, and still not subject to a reliable deadline.

Use three explicit policy modes.

Continue holding the release

Use this for production nodes that have not passed compatibility testing or that support a workload with no spare capacity.

Configure an update deferral in the declarative software update settings. Apple documents macOS deferral periods from 1 to 90 days for software updates or upgrades. A deferral controls when a release is offered. It does not mean that an independently enforced target can never install. (Apple’s software update settings documentation)

Acceptance checks:

• The device remains on the intended system version.
• The release is hidden or delayed according to the declaration.
• A later enforcement declaration has not accidentally entered the queue.
• Your dashboard shows the reason for the hold.

Open installation to the user or operator

Use this for development Macs, non-critical build nodes, and pilot groups where you want installation to be available without immediate enforcement.

This mode is useful when your team needs to test Xcode, package managers, signing tools, virtualization, or internal agents before setting a deadline. It is not a substitute for status reporting. “The update is visible” is not evidence that it was downloaded or prepared.

Keep the target group narrow. A broad smart group based only on enrollment status can include a production CI Runner by mistake.

Enforce installation by a deadline

Use this when a node must reach a known version by a maintenance cutoff.

Apple’s SoftwareUpdateEnforcementSpecific declaration supports enforcement by a specified time. If multiple configurations target newer versions, Apple states that the configuration with the earliest target date and time is processed first. Older or equal targets are ignored after the device reaches a newer version.

That queue behavior is important. Do not publish several overlapping declarations without a removal policy. A stale declaration may remain visible in the service even though the device has already moved beyond its target.

A simple decision rule works well:

• If the node has no tested fallback and no spare capacity, hold.
• If the node is a pilot or development machine, offer.
• If the node has passed workload recovery tests and has a maintenance window, enforce.

Mixed macOS 26 and macOS 27: split the fleet before you split the rollout

A mixed environment needs two management tracks. Do not use one old update workflow for macOS 26 and one new workflow only after macOS 27 failures appear.

Create groups using at least:

• Current major and minor system version.
• Target operating system and build.
• Device model and Apple silicon status.
• Supervision and enrollment state.
• Bootstrap Token escrow state.
• Workload role.
• Whether the node can be drained or replaced.

How should a mixed macOS 26 and macOS 27 fleet receive updates? Keep the groups separate until the macOS 27 declaration path has passed its full acceptance gate. macOS 26 devices can follow their supported management path, while macOS 27 devices receive the declarative configuration. Do not let a version-agnostic rule apply a 27.0 target to a macOS 26 node.

Validate the match before publishing the declaration:

1. Query the device’s current version.
2. Confirm the device belongs to the intended role group.
3. Confirm the target build is available for that model and channel.
4. Confirm the declaration scope contains only the pilot devices.
5. Confirm the status report is associated with the correct declaration identifier.
6. Confirm the production group is excluded.

Your exit condition for dual-track management should be explicit:

• All macOS 27 pilot nodes have completed declaration activation.
• The target version and build are visible in your compliance data.
• At least one enforced installation has completed.
• Remote access has returned after restart.
• CI agents have passed post-reboot health checks.
• Every remaining macOS 26 node has an upgrade, replacement, or retirement plan.

Without that final condition, “temporary mixed mode” becomes permanent operational debt.

Apple silicon and unattended enforcement: authorization is the gate

An unattended Apple silicon Mac cannot be treated like an interactive laptop. You must validate the authorization chain before scheduling a forced update.

Check these prerequisites:

• The Mac is supervised.
• The enrollment method supports the required management workflow.
• The MDM profile advertises bootstrap token capability.
• A bootstrap token has been created and escrowed.
• The target system version and build are accepted by the device.
• The volume ownership and local authorization state support the planned update.
• The device can restart without a human at the keyboard.

Apple documents that a bootstrap token can authorize an enforced software update on a supervised Mac with Apple silicon. The management service must advertise com.apple.mdm.bootstraptoken in its server capabilities, retrieve the token when required, and escrow it through the device management service. Apple also documents checking SecurityInfoCommand for BootstrapTokenRequiredForSoftwareUpdate. (Apple’s bootstrap token deployment guidance)

How do you know an unattended update is authorized? Do not infer authorization from enrollment alone. Check the security information response, bootstrap token escrow state, and the actual transition into prepared or installing. If the node stops at a user prompt, your production test has failed even if the declaration is active.

Use a strict quarantine rule:

• No bootstrap token: keep the node out of forced production rollout.
• No successful restart test: keep the node out of forced production rollout.
• No remote check-in after restart: move the workload to a replacement node.
• No confirmed volume ownership or authorization path: use manual maintenance.

Apple notes that Macs with Apple silicon require a volume owner to perform an update or upgrade in normal authorization flows. A bootstrap token is what allows a supported management service to make the enforced path unattended.

CI Runner rollout: drain first, update second, accept work last

A CI Runner is not healthy because sw_vers reports the desired version. It is healthy when it can complete the operational sequence that your build system depends on.

Use this five-stage rollout:

Step one: drain the Runner

Stop new jobs. Allow active jobs to finish or move them to a known failure-safe state. Record the queue depth and the node’s current assignment.

Do not start an update while the Runner is holding a release build, signing task, or long-running integration test unless the workload is explicitly restart-safe.

Step two: apply the declaration to a pilot

Publish the target version or build to one non-critical Runner. Confirm declaration activation before enforcing the installation time.

Record:

• Device identifier.
• Current system version.
• Target version and build.
• Declaration identifier.
• Enforcement time.
• Current update status.
• Last check-in time.

Step three: follow the state transitions

A useful sequence is:

waiting → downloading → prepared → installing → none

A failure state requires investigation. Do not immediately resend a legacy command. Compare the device status, available release data, authorization state, storage condition, and restart blockers.

The Apple software update process guide explains the preparation and restart behavior that your runbook should account for. The guide is more useful here than a generic version check because it helps you distinguish preparation failure from post-restart recovery failure.

Step four: validate remote recovery

After restart, verify:

• The Mac checks in to the management service.
• Remote access is available.
• Disk encryption and login state are as expected.
• The CI agent service starts.
• The agent reports the correct labels and capabilities.
• Required certificates, keychains, SDKs, and signing identities remain usable.
• The node does not accept jobs before these checks finish.

You can expose management controls and operational references through your MacHTML console, but your acceptance logic should remain independent of a single dashboard status. Store the raw device status and the post-reboot health result.

Step five: re-enable job intake

Only return the Runner to service after it passes a real smoke build. The smoke build should exercise the failure points that matter to you, not just an echo command.

Good gates include:

• Source checkout.
• Dependency resolution.
• Compiler or interpreter startup.
• Test execution.
• Artifact creation.
• Code signing if applicable.
• Cache access.
• Artifact upload.
• Clean workspace teardown.

Set the rollout decision from evidence:

• Continue in batches if all gates pass.
• Pause if installation succeeds but status reporting or remote recovery is inconsistent.
• Use parallel Mac capacity if the node cannot be safely drained or if the restart window exceeds your available tolerance.

The migration decision: keep the node, pause it, or add parallel capacity

Use this decision matrix before expanding beyond the pilot:

The strongest acceptance signal is not a green version field. It is a complete chain from declaration to workload recovery.

Current workflow versus parallel Mac capacity

If your current fleet depends on old MDM update commands, it has three real weaknesses: the console can report delivery without proving enforcement, mixed macOS versions can follow different control behavior, and a failed restart can remove a production Runner without an immediate replacement.

A parallel remote Mac changes the risk calculation. You can drain the original node, test the declaration on an isolated machine, and keep build capacity available while the upgraded node proves remote recovery and CI re-entry. It is not automatically the best choice for a permanently stable, high-volume fleet that should own dedicated hardware. It is useful when you need temporary capacity, a controlled migration window, or a safe test target without interrupting production.

If you cannot provide a non-critical pilot, a restart recovery test, and a spare path for important jobs, prepare temporary Mac capacity before publishing a forced declaration. Review the MacHTML help resources for access and operating details, then choose capacity based on node count, unattended operation, and the length of your maintenance window. For short migration projects, MacHTML remote Mac options can be evaluated as a parallel environment rather than as a replacement for every long-term production node.