System upgrades
Treat upgrades as reversible engineering changes
All nodes operate normally year-round, 365 days a year, with no scheduled downtime. For user-initiated macOS or toolchain upgrades, verify compatibility first and keep a recovery path.
A
Create a backup before upgrading
Back up essential data outside the code repository, build settings, dependency lockfiles, and artifacts. Record the current macOS, Xcode, command-line tools, and key dependency versions.
B
Verify toolchain compatibility
Check the project’s minimum system requirements, supported Xcode range, dependency manager, and CI scripts. Run a test build before touching the production pipeline.
C
Choose a low-risk time
Avoid team release, signing, and artifact delivery windows. Notify affected collaborators and pause automated jobs that could simultaneously rewrite dependencies or build caches.
D
Define rollback conditions in advance
Specify which failed tests will stop the upgrade, and keep the original version record, backup location, and recovery steps. After recovery, recheck SSH, the Xcode path, dependencies, and artifact output.
Four checks after upgrading
Each check should leave command output or a pipeline record to make regressions easier to trace.
System and Xcode versions are correct
Dependencies can be reproduced from the lockfile
The test build passes completely
Artifacts can be exported and retrieved